diff --git a/coding_style_and_standards.md b/coding_style_and_standards.md index d43e842..2f58623 100644 --- a/coding_style_and_standards.md +++ b/coding_style_and_standards.md @@ -31,20 +31,20 @@ maintained by the ManageIQ team. * We follow, with some exceptions, the [original Ruby style guide](https://github.com/bbatsov/ruby-style-guide). Any changes we have that deviate from the default style guide are enumerated - in the [.rubocop_base.yml](.rubocop_base.yml) file, which is inherited by most - projects in the ManageIQ organization. + in the [manageiq-style base.yml](https://github.com/ManageIQ/manageiq-style/blob/master/styles/base.yml) file, + which is inherited by most projects in the ManageIQ organization. ## Documentation We use [yardoc](https://yardoc.org/) to create inline code documentation. For now documentation is scarce but -we encourage contributors to add it whenever possible. Until more of the codebase is documented, we limit the created -documentation to those files that are well documented. +we encourage contributors to add it whenever possible. Until more of the codebase is documented, we limit the created +documentation to those files that are well documented. Please try to document methods that are used by external teams, like providers. These are the integration API for them and should be documented best. To view the documentation online visit [rubydoc.info](http://www.rubydoc.info/github/manageiq/manageiq). For a local version you can run `bundle exec yard` and view the html docs in `/doc/index.html`. When writing documentation you -should add your source files to `/.yardopts` and run `bundle exec yard server -r`. This will create a local +should add your source files to `/.yardopts` and run `bundle exec yard server -r`. This will create a local documentation server which regenerates the docs on each request. ## Logging @@ -88,7 +88,6 @@ documentation server which regenerates the docs on each request. ## Commits * Write a good commit message. The format for a commit message is as follows. - Also [read more](http://goo.gl/w11us) on writing good commit messages. * A short summary of the commit under 72 characters. Do not use a ticket number as the subject alone. * A blank line. @@ -100,18 +99,23 @@ documentation server which regenerates the docs on each request. SHA references to other commits, and even raw data to make the purpose of the commit clearer (e.g. "Was broken by commit 0f3a459b"). * A blank line if you've written a body. - * References to any Bugzilla tickets or Github Issues, one per line if + * References to any GitHub Issues or other ticketing systems, one per line if there are multiple. - * Bugzilla tickets should be in the form of a full URL to the ticket. - * Github issues should be of the form "Issue #n", where n is the - issue number. + * GitHub issues should be of the form "Issue #n", where n is the issue number. + * Other tickets should be in the form of a full URL to the ticket or the form + appropriate for that system. * Each commit should have its own unique subject. Do not use the same subject for a series of commits in a branch of work. +* Avoid using [@-mentions](https://github.com/blog/821) in the body of the commit + message as GitHub will notify the user every time the commit is pushed. As a + corollary, code that uses `@` could accidentally be interpreted as an @-mention, + so all code snippets in commit messages should be marked within code block + formatting. * Keep commits small by committing often and only include related changes and tests together. * You may be doing too much in a commit if... * You can't get the subject of the commit message under 72 characters - * You are using a lot of "ands" or "ors" in the commit message + * You are using a lot of "and"s or "or"s in the commit message * You find yourself using lots of bullet points to enumerate all the work the commit does. * Squash (combine) commits to keep logical units of changes grouped together @@ -138,7 +142,7 @@ documentation server which regenerates the docs on each request. change_ems_amazon_to_be_region_specific ``` -* Write a good pull request message. By default, Github will use your +* Write a good pull request message. By default, GitHub will use your branch name as the title. Adjust the title if this is not appropriate for the pull request. * See [writing a good commit message](#commits) for information about @@ -153,7 +157,7 @@ documentation server which regenerates the docs on each request. code smells. * Try to avoid having a commit with, for example, a spelling mistake, that is fixed in a subsequent commit in the same pull request. Use `git rebase -i` - to clean up those commits to keep the history clean. + to squash those commits to keep the history clean. * If a pull request involves UI changes, consider adding a before/after set of screenshots to show what has changed visually. * Use [@-mentions](https://github.com/blog/821) to request reviews from @@ -164,7 +168,7 @@ documentation server which regenerates the docs on each request. ## Error and Issue Reporting * Under no circumstances should customer names or customer related information - be referenced in Github issues, error reports, commits, or pull requests. + be referenced in GitHub issues, error reports, commits, or pull requests. * For UI errors, the error message and stack trace are usually in production.log. A snippet from there with the entire UI transaction is needed, including the error message and the stack trace. A UI transaction @@ -193,7 +197,7 @@ documentation server which regenerates the docs on each request. Most items are handled by a queue worker of some type, so for those it is most useful to have: - + * The MiqQueue.put or MiqQueue.merge line from the worker that placed the item on the queue. * Context around why the item was placed on the queue. For example, if @@ -229,44 +233,44 @@ When extracting code into a new gem or creating a new gem: ## Git how-to -Note after the changes in this section, you will need `git push -f `if you have +Note after the changes in this section, you will need `git push -f `if you have already pushed them before. * Reword/squashing/reordering a commit - To modify with recent commit in current branch, first do + To modify with recent commit in current branch, first do `git rebase -i origin branch-name`. To modify a specific commit, use `git rebase -i SOME_COMMIT_ID^` instead. - git will popup a vi window to let you do modification on commits, press + git will popup a vi window to let you do modification on commits, press `:wq` after done. - + * Reword a commit - - Change the `pick` before the commit you want to reword to `edit` and edit + + Change the `pick` before the commit you want to reword to `edit` and edit its message in popup vi window. - + * Squashing commits - - Change the `pick` before the commit you want to squach to `squash` and edit - the commit message after squash in a following popup vi window. A commit + + Change the `pick` before the commit you want to squach to `squash` and edit + the commit message after squash in a following popup vi window. A commit will be squashed with its previous commit. - + * Reordering commits - + Reordering them in this vi window will reorder the commits. * Amend a commit You can commit first and rebase it in the previous section. Or if you want to amend most recent commit, you can: `git commit some_file --amend`. - + * Deleting a commit You can delete commits by delete corresponding lines in `git rebase`. Or if you want to delete most recent commit, you can `git reset --hard HEAD^`. If you want to go back to a specific commit and delete commits after that, use `git reset --hard commit-hash`. - + * Uncommit a file from an existing commit ``` @@ -277,8 +281,6 @@ already pushed them before. ## TODO * Rails style guide see https://github.com/bbatsov/rails-style-guide -* Bugzilla how-to - * how to copy commit details / clone a ticket # License