-
Notifications
You must be signed in to change notification settings - Fork 32
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
(SIMP-2053) New Contributors Guide (#129)
* (SIMP-2053) New Contributors Guide We have moved our code review process to Github, and the old Contributors guide needed to be updated. SIMP-2053 #close Change-Id: I931c2a91e14bb35b11c6af90f2d7cfa541cc272c * Added instructions for allowing maitainers to edit pull requests. * Added link to GH docs Change-Id: I54ba7ca5b9aeb7e634f7385eda53721fdb9044c2 * Added a hub section Change-Id: I0659312faf51a2b68b808ddf495f177e46b6c613 * Updated to be more community friendly * Removed 'hub'-specific stuff from the Contribution Procedure * Added a Maintenance Procedure for maintainers * We may want to split this out in the future * Fixed some typos * Updated the resources links to not be redundant Change-Id: I70e584b95fba47b14c1cbd1507fbfa240d8ce1c8 * Removed long version Change-Id: Ia2045f0555d6e28367dc656d0172782d929fb507 * fixed a typo
- Loading branch information
1 parent
d7d4020
commit ba9568a
Showing
5 changed files
with
119 additions
and
91 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,107 +1,91 @@ | ||
| .. _gsg-contributors_guide-contribution_procedure: | ||
|
|
||
| Contribution Procedure | ||
| ====================== | ||
|
|
||
| #. `Fork`_ the project on `GitHub`_ | ||
|
|
||
| #. Make a new `feature branch`_ for your changes | ||
|
|
||
| * Suggestion: name the branch after the issue (e.g., 'SIMP-999') | ||
|
|
||
| #. Make your changes! | ||
|
|
||
| * SIMP contributions should observe the `Puppet Language Style Guide`_ | ||
| conventions where feasible | ||
| * Contributions should ideally include relevant spec and/or acceptance tests | ||
|
|
||
| #. Save your changes in a **single commit** | ||
| We use the standard `GitHub workflow`_ for SIMP development with the exception | ||
| that we use a `Squash and Merge`_ merge method for pulling in changes, in order | ||
| to maintain a more legible commit history on `master`. | ||
|
|
||
| * Use the following commit message conventions: | ||
| #. Search the `SIMP JIRA`_ for an open ticket that is relevant to the issue or | ||
| open a new one. | ||
|
|
||
| .. code-block:: none | ||
| #. Use the `GitHub GUI to fork and clone`_ the repository (we'll use | ||
| ``pupmod-simp-iptables`` for the rest of this walkthrough) | ||
|
|
||
| (SIMP-999) Fix the broken thing [50 chars max] | ||
| #. Clone the repo you want to work on: | ||
|
|
||
| Discussion about the fix (if needed) [each line: 72 chars max] | ||
| * ``git clone git@github.com:<YOUR_GITHUB_NAME>/pupmod-simp-iptables iptables`` | ||
|
|
||
| SIMP-998 #comment Comment on a related issue [72 chars max] | ||
| SIMP-999 #close | ||
| #. Enter the directory and create a `feature branch`_: ``git checkout -b SIMP-XXXX`` | ||
|
|
||
| * The commit message should be the following format: | ||
| #. Do your work! `(Including tests, of course)` | ||
|
|
||
| * First line: | ||
| #. Commit your work. We will `squash`_ your `pull request`_ into one commit | ||
| when we merge it, so you can use as many commits as you'd like. | ||
|
|
||
| * Start with the Issue name in parentheses [e.g., ``SIMP-999``], | ||
| followed by a summary of the change | ||
| * No longer than **50** characters | ||
| * Followed by a line of white space | ||
| .. IMPORTANT:: | ||
| The **first** commit should use the `Commit Message Conventions`_ | ||
|
|
||
| * Subsequent lines: | ||
| #. Push your changes to Github on your feature branch: | ||
|
|
||
| * Each line should be no longer than **72** characters | ||
| * ``git push origin SIMP-XXXX`` | ||
|
|
||
| * Issue references: | ||
| #. Using the GitHub GUI, create a `pull request`_ from your feature branch to | ||
| the branch of the original repo that you want to contribute to. Leave the | ||
| '`Allow edits from maintainers`_' checkbox checked to let a team member add | ||
| add commits to your pull request. | ||
|
|
||
| * `JIRA issues can be referenced`_ at the end of the commit message | ||
| * It is recommended to only use the commands ``#comment`` and ``#close`` | ||
| * Avoid ``#resolve`` and ``#time`` as it will not update JIRA until | ||
| after the issue is merged | ||
| #. `Travis-CI`_ will run the spec tests for the branch and a member of the SIMP | ||
| team will `review`_ your submission. You should receive emails from Github as | ||
| the code reviews progress. | ||
|
|
||
| #. Push your changes up to your forked repo on GitHub | ||
| Commit Message Conventions | ||
| -------------------------- | ||
|
|
||
| #. Create a `pull request`_ ("PR") on GitHub using your new branch | ||
| An example commit message that following the SIMP conventions: | ||
|
|
||
| * The pull request should contain a **single** new commit | ||
| .. code-block:: none | ||
| * Use ``git rebase -i`` to squash commits (use ``git rebase -i HEAD~n`` to | ||
| go back ``n`` commits) | ||
| (SIMP-999) Fix the broken thing [50 chars max] | ||
| #. `Travis-CI`_ will notice the pull request and run CI tests | ||
| Discussion about the fix (if needed) [each line: 72 chars max] | ||
| * Travis-CI will run tests based on the `.travis.yml`_ file in the | ||
| repository's top-level directory | ||
| * Travis-CI results can be seen in the PR on GitHub and are posted to the | ||
| project's `HipChat`_ channel | ||
| SIMP-998 #comment Comment on a related issue [72 chars max] | ||
| SIMP-999 #close | ||
| #. After passing Travis-CI tests, the GitHub pull request must be picked up in | ||
| `GerritHub`_ for code review | ||
| The first commit message should be the following format: | ||
|
|
||
| * **NOTE:** Currently, this is a *manual* process and requires a project | ||
| administrator | ||
| * First line: | ||
|
|
||
| #. Pull requests are code reviewed on `GerritHub`_ | ||
| * Start with the Issue name in parentheses [e.g., ``(SIMP-999)``], followed | ||
| by a summary of the change | ||
| * No longer than **50** characters | ||
| * Followed by a line of white space | ||
|
|
||
| * If you need to update an existing pull request, `amend`_ the pull | ||
| request's commit using the following commands: | ||
| * Subsequent lines: | ||
|
|
||
| * ``git add`` or ``delete`` (this stages the build with the relevant | ||
| changes; ``add --all`` will add all the new changes, otherwise ``add`` | ||
| or ``delete`` to tailor your changeset) | ||
| * ``git commit --amend`` (this amends the previous commit) | ||
| * Each line should be no longer than **72** characters | ||
| * Describe the previous behavior, why it was changed, and the changes in | ||
| detail | ||
|
|
||
| * **NOTE:** The final line of the amended commit message must include | ||
| the Gerrit review's Change-ID | ||
| (example: ``Change-Id: Ie536768505a1baff45d6ad3ae4de9e7501ffb53c``) | ||
| * ``git push --force`` (this sends back to the ``master`` branch) | ||
| * Issue references: | ||
|
|
||
| * If you prefer to amend your change in Gerrithub, you can use the | ||
| `git-review`_ package to make submitting patch sets easier | ||
| * `JIRA issues can be referenced`_ at the end of the commit message | ||
| * It is recommended to only use `JIRA Smart Commit Tags`_ ``#comment`` and | ||
| ``#close`` | ||
| * Avoid ``#resolve`` and ``#time`` as it will not update JIRA until | ||
| after the issue is merged | ||
|
|
||
| * Install the ``git-review`` package | ||
| * Add the remote: ``git remote add gerrit <url>`` | ||
| * Run: ``git-review -r gerrit`` | ||
|
|
||
| #. After the `GerritHub`_ review is approved, the changes will be automatically | ||
| merged into the original `GitHub`_ repository | ||
|
|
||
| .. _.travis.yml: http://docs.travis-ci.com/user/build-configuration/ | ||
| .. _Fork: https://help.github.com/articles/fork-a-repo | ||
| .. _GerritHub: https://review.gerrithub.io/#/q/is:open+project:%255Esimp.* | ||
| .. _GitHub: https://github.com/simp | ||
| .. _HipChat: https://simp-project.hipchat.com/chat | ||
| .. _JIRA issues can be referenced: https://confluence.atlassian.com/bitbucket/processing-jira-software-issues-with-smart-commit-messages-298979931.html | ||
| .. _Puppet Language Style Guide: https://docs.puppetlabs.com/guides/style_guide.html | ||
| .. _Travis-CI: https://travis-ci.org/simp | ||
| .. _amend: https://www.atlassian.com/git/tutorials/rewriting-history/git-commit--amend | ||
| .. _GitHub Workflow: https://guides.github.com/introduction/flow/ | ||
| .. _Squash and Merge: https://github.com/blog/2141-squash-your-commits | ||
| .. _SIMP JIRA: https://simp-project.atlassian.net | ||
| .. _GitHub GUI to fork and clone: https://help.github.com/articles/fork-a-repo/ | ||
| .. _feature branch: https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow | ||
| .. _git-review: https://github.com/openstack-infra/git-review | ||
| .. _squash: https://github.com/blog/2141-squash-your-commits | ||
| .. _pull request: https://help.github.com/articles/using-pull-requests | ||
| .. _Allow edits from maintainers: https://help.github.com/articles/allowing-changes-to-a-pull-request-branch-created-from-a-fork/ | ||
| .. _Travis-CI: https://travis-ci.org/simp | ||
| .. _review: https://help.github.com/articles/reviewing-proposed-changes-in-a-pull-request/ | ||
| .. _JIRA issues can be referenced: https://confluence.atlassian.com/bitbucket/processing-jira-software-issues-with-smart-commit-messages-298979931.html | ||
| .. _JIRA Smart Commit Tags: https://confluence.atlassian.com/bitbucket/processing-jira-software-issues-with-smart-commit-messages-298979931.html |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,47 @@ | ||
| Maintenance Procedure | ||
| ===================== | ||
|
|
||
| If you're a SIMP maintainer, you're in the right spot! Otherwise, you'll want | ||
| to head over to the :ref:`gsg-contributors_guide-contribution_procedure`. | ||
|
|
||
| This section exists to document the correct procedure for SIMP Maintainers to update and work with code. | ||
|
|
||
| SIMP Maintainer contributions follow the :ref:`gsg-contributors_guide-contribution_procedure`. | ||
|
|
||
| .. NOTE:: | ||
| It is recommended that all SIMP Maintainers use the `hub`_ Git extensions | ||
| and all examples in this section will expect that `hub`_ is installed and | ||
| ready for use. | ||
|
|
||
| Amending Changes to Submitted Pull Requests | ||
| ------------------------------------------- | ||
|
|
||
| #. Clone the source repo: | ||
|
|
||
| * ``git clone https://github.com/simp/simp-doc doc`` | ||
|
|
||
| .. IMPORTANT:: | ||
| We use 'git clone' instead of 'hub clone' so that we can't accidentally | ||
| push to the main SIMP repositories. While we have protected branches | ||
| for the critical components, one wrong command and and life can get | ||
| unpleasant. | ||
|
|
||
| #. Pull down the pull request as found on the GitHub GUI: | ||
|
|
||
| * ``hub checkout https://github.com/simp/pupmod-simp-doc/pull/28`` | ||
|
|
||
| #. Review the code or make your additional changes | ||
|
|
||
| * ``HACK HACK HACK`` | ||
|
|
||
| #. Add a new commit with your changes: | ||
|
|
||
| * ``git commit -a -m "I made the docs better"`` | ||
|
|
||
| #. Push your new commit to the feature branch of the **owner** of the pull | ||
| request. In this example, the owner is `jeefberkey`, and the feature branch | ||
| name is `SIMP-1897`: ``hub push jeefberkey SIMP-1897`` | ||
|
|
||
| #. The pull request has been updated, and participants have received an email | ||
|
|
||
| .. _hub: https://hub.github.com/ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -8,4 +8,5 @@ Contributing to SIMP | |
|
|
||
| Introduction | ||
| Contribution_Procedure | ||
| Maintenance_Procedure | ||
| Resources | ||