From 0b6451d92170b43b1c1e0c025b0b8d8b42f2c594 Mon Sep 17 00:00:00 2001 From: Drew Walters Date: Wed, 13 Sep 2017 00:01:56 -0500 Subject: [PATCH] docs(CONTRIBUTING.rst): add contribution guide - Add code of conduct reference, support channels - Outline types of issues - Explain GerritHub workflow Closes #157 https://github.com/att-comdev/armada/issues/157 Change-Id: Ice74bc84c99b4cc8e4a4d8e8955d4aa5575b5021 --- CONTRIBUTING.rst | 305 ++++++++++++++++++++++++++++++ docs/source/development/index.rst | 1 + 2 files changed, 306 insertions(+) create mode 100644 CONTRIBUTING.rst diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 00000000..b9f671c9 --- /dev/null +++ b/CONTRIBUTING.rst @@ -0,0 +1,305 @@ +Contribution Guidelines +======================= +The Armada project maintainers would like to thank you for your interest in +contributing to Armada. This document outlines the processes and procedures +involved in contributing to Armada. + +Code of Conduct +--------------- +By contributing to Armada, you are agreeing to uphold the +`Contributor Convenant Code of Conduct `_. Please +familiarize yourself with it before contributing. + +Support +------- +Project maintainers regularly monitor the Armada GitHub +`issues `_ page for design and +development related questions. Maintainers will try to answer questions located +there as quickly as possible. + +Reporting an Issue +------------------ +All bugs and features are tracked using the Armada GitHub +`issues `_ page. Before submitting +an issue, please check the `troubleshooting guide `_. If the issue still persists, please file an +official bug report on the `issues `_ +page if one does not already exist. When filing an issue, please follow the issue +template and be as descriptive as possible. + +After an issue is created, project maintainers will assign labels indicating +the issue type. + ++-------------+---------------------------------------------------------------+ +| Label | Description | ++=============+===============================================================+ +| bug | Indicates a confirmed bug or other unexpected behavior | ++-------------+---------------------------------------------------------------+ +| ehancement | Feature request | ++-------------+---------------------------------------------------------------+ +| question | Indicates a question | ++-------------+---------------------------------------------------------------+ +| docs | Assigned to issues indicating missing or incomplete | +| | documenation | ++-------------+---------------------------------------------------------------+ +| duplicate | Assigned to issues that are duplicates of previously reported | +| | issues | ++-------------+---------------------------------------------------------------+ +| help-wanted | Project maintainers would like community help resolving the | +| | reported issue | ++-------------+---------------------------------------------------------------+ +| invalid | Assigned to indicate an invalid issue type | ++-------------+---------------------------------------------------------------+ + +Additionally, issues can also be assigned a label indicating their size or +complexity. + ++-------------+---------------------------------------------------------------+ +| Label | Description | ++=============+===============================================================+ +| size/small | Smaller than average change | ++-------------+---------------------------------------------------------------+ +| size/medium | Average change size requiring an average amount of testing | +| | and review | ++-------------+---------------------------------------------------------------+ +| size/large | Larger than average change requiring heavy testing and review | ++-------------+---------------------------------------------------------------+ +| starter | Issue is a good fit for a new contributor | ++-------------+---------------------------------------------------------------+ + +If the issue type is not clear or more information is needed, project +maintainers will reach out in the comment section to request additional +details. + +Submitting a Patch +------------------ +This section focuses on the workflow and lifecycle of Armada patches. +Development specific information can be found in the Armada +`developers' guide `_ + +Armada accepts patches through GerritHub changes. Each commit pushed to +GerritHub is recognized as a "change" (the equivalent of a GitHub pull +request). When a change is pushed to GerritHub for review, it contains an +intial patch set that shows all of the revised changes. When a Gerrit change is +amended, a new patch set is created to show the differences from the previous +patch set. + +The general workflow for submitting a change is: + + 1. Select an issue - select an issue from the Armada GitHub + `issues `_ page by commenting + on the issue itself. + 2. Submit a GerritHub change for review. + 3. Review - Project maintainers and contributors will review the change on + GerritHub and may request that additional patch sets be submitted before + the change can be merged. + 4. Merge or close - the change is either merged or closed by the project + maintainers. + +Using GerritHub +~~~~~~~~~~~~~~~ +In order to use GerritHub, you must first authorize GerritHub to access your +GitHub profile and import SSH public keys by signing in at +`gerrithub.io `_. + +In order to submit a change using GerritHub, the +`git review `_ tool must be +installed. Git-review can be installed using Python +`pip `_ by executing: + +.. code-block:: bash + + pip install git-review + +Git-review can also be intalled on Ubuntu by executing: + +.. code-block:: bash + + apt-get install git-review + +After installing git-review, clone the Armada repository from GerritHub + +.. code-block:: bash + + git clone https://review.gerrithub.io/att-comdev/armada + +Change to the repository root directory and configure git-review to use +GerritHub. This will verify that login is possible using your imported +`SSH public keys `_. + +.. code-block:: bash + + cd armada + git review -s + +If you require authentication over HTTPS, you will need to generate an +`HTTPS password `_. +Once you have generated an HTTPS passowrd, add the repository to your remote +repositories + +.. code-block:: bash + + git remote add gerrit https://@review.gerrithub.io/a/att-comdev/armada + +Now that your local repository is configured, create a local branch for your +change using the format `//`, where `TYPE` is the type +of change (i.e. feat, bug, docs), `SCOPE` is the Armada component where +the change will occur (i.e. api, cli, source), and `DESC` is a hyphenated +description of the change (i.e. new-endpoints). + +An example branch name for a feature that adds more API endpoints might be +`feat/api/new-endpoints`. + +.. code-block:: bash + + git checkout -b + +When you are ready to submit your local changes for review, commit your +changes: + +.. code-block:: bash + + git commit + +Armada uses Karma inspired `Semantic Commit Messages +`_ for all changes. + +.. code-block:: bash + + (): + + <DESCRIPTION> + + Closes <ISSUE-REFERENCE> + +In the above template, `TYPE` refers to the type of change, `SCOPE` refers to +the area where the change occurs (i.e. api, cli, source), `TITLE` is the title +of the commit message, `DESCRIPTION` is a desription of the change, and +`ISSUE-REFERENCE` is a link to the GitHub issue the change addresses. + +Below is a list of possible types: + ++----------+-------------------------------------------------------+ +| Type | Description | ++==========+=======================================================+ +| feat | Adds a new feature | ++----------+-------------------------------------------------------+ +| fix | Fixes a confirmed bug or other unexpected behavior | ++----------+-------------------------------------------------------+ +| docs | Documentation update | ++----------+-------------------------------------------------------+ +| style | Reformats existing code to conform to the style guide | ++----------+-------------------------------------------------------+ +| refactor | Refactors existing code to improve readability | ++----------+-------------------------------------------------------+ +| test | Adds additional tests | ++----------+-------------------------------------------------------+ + +.. NOTE:: + + The scope component of a commit message may be ommited if the change + covers more than a single component of Armada. + +An commit message for a change that adds a new API endpoint might resemble the +following example: + +.. code-block:: bash + + feat(api): add new API endpoint + + New api endpoint /foo/status returns the status of foo. + + Closes #999 https://github.com/att-comdev/armada/issues/999 + +.. NOTE:: + + It is necessary to leave a blank line between the commit title and + desciption in order for a change to appear properly on GerritHub. + +Since each commit is represented as a "change" in GerritHub, multiple commits +should be squashed into one commit before pushing to GerritHub for review. To +squash redundant commits, execute: + +.. code-block:: bash + + git rebase -i + +Change "pick" to "squash" next to every commit except for the one containing +the commit message you wish to use for your Gerrit change. + +To push your change for review, execute: + +.. code-block:: bash + + git review + +Your change will now be visible on GerritHub for review. In order to amend your +change after pushing it for review, you will need to create additional +patch sets. + +In order to create an additional patch set, modify your exisiting commit and +push your new changes for review + +.. code-block:: bash + + git commit --amend + git review + +An additional patch set will now appear on the original GerritHub change. + +Work in Progress +~~~~~~~~~~~~~~~~ +Uploading changes that are not yet complete is highly encouraged in order to +receive early feedback from project maintainers and other contributors. To +label your change as a work in progress, leave a code review of your own +patch set with a vote of -1 and a comment indicating that your patch set is a +work in progress. + +Rebasing A Commit +~~~~~~~~~~~~~~~~~ +If changes have occurred to the master branch since your local branch was last +updated, you will need to rebase your commit with the new changes. + +Update master locally + +.. code-block:: bash + + git checkout master + git remote update + +Return to your branch and rebase with master + +.. code-block:: bash + + git checkout <BRANCH> + git rebase origin/master + +After resolving all merge conflicts, resume the rebase + +.. code-block:: bash + + git rebase --continue + +Code Review Workflow +~~~~~~~~~~~~~~~~~~~~ +Once a change is submitted to GerritHub, project maintainers and other +contributors will review it and leave feedback. In order for a change to be +merged, a change must have at least two +2 votes from project maintainers, and +must pass all Jenkins continuous integration tests. + +Continuous Integration Testing +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +All patch sets submitted to the Armada GerritHub undergo continuous integration +testing performed by Jenkins. If the Jenkins build is successful, Jenkins will +leave a code review with a vote of +1. If the Jenkins build fails, Jenkins will +leave a code review with a vote of -1. + +In order to ensure that your patch set passes the continuous integration tests +and conforms to the PEP8 style guide, execute: + +.. code-block:: bash + + tox -e pep8 + tox -e py27,py35 + tox -e coverage diff --git a/docs/source/development/index.rst b/docs/source/development/index.rst index d4778dcc..1c34ff69 100644 --- a/docs/source/development/index.rst +++ b/docs/source/development/index.rst @@ -11,3 +11,4 @@ Developers Guide :caption: Contents: getting-started.rst + ../../../CONTRIBUTING.rst