diff --git a/doc/source/_static/code-review-ci.png b/doc/source/_static/code-review-ci.png new file mode 100644 index 00000000..189af454 Binary files /dev/null and b/doc/source/_static/code-review-ci.png differ diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst new file mode 100644 index 00000000..a239e059 --- /dev/null +++ b/doc/source/contributing.rst @@ -0,0 +1,129 @@ +How to contribute +================= + +ARA Records Ansible is an open source community project and welcomes +contributions, whether they are in the form of feedback, comments, suggestions, +bugs, documentation, code, or code reviews. + +The ARA code review and CI infrastructure is hosted by `opendev.org `_ +which provides Gerrit for code review, Zuul for CI/CD as well as many other +systems. + +All new patches are automatically tested with lint, unit and a variety of +integration test scenarios. +The end result is higher standards, better code, more testing, less regressions +and more stability. + +.. image:: _static/code-review-ci.png + +Running tests locally +--------------------- + +- Unit tests: ``tox -e py37`` +- Linters tests (pep8/flake8/bandit/bashate/black/isort/etc): ``tox -e linters`` +- Documentation tests (builds to ``docs/build/html``): ``tox -e docs`` +- Integration tests: ``tox -e ansible-integration`` + +Issues and pull requests +------------------------ + +ARA has several projects that are mirrored to GitHub: + +- https://opendev.org/recordsansible/ara -> https://github.com/ansible-community/ara +- https://opendev.org/recordsansible/ara-web -> https://github.com/ansible-community/ara-web +- https://opendev.org/recordsansible/ara-infra -> https://github.com/ansible-community/ara-infra + +While new issues, bugs and feature requests should be filed on GitHub, we are +unable to accept pull requests on GitHub at this time. + +We would appreciate the opportunity to accept them in the future by trying +`Gerritbot `_ to +synchronize pull requests to Gerrit. + +In the meantime, what follows are the required steps in order to send a patch +to Gerrit. + +Set up your Ubuntu Launchpad account +------------------------------------ + +OpenDev's Gerrit_ instance currently uses Launchpad_ for authentication. +If you do not already have a Launchpad account, you will need to create one +here_. + +.. _here: https://login.launchpad.net/+login + +Set up your Gerrit code review account +-------------------------------------- + +If you'll be contributing code or code reviews, you'll need to set up your +Gerrit code review account. + +Once you have your Launchpad account, you will be able to sign in to +`review.opendev.org`_. + +To be able to submit code, Gerrit needs to have your public SSH key in the +same way Github does. To do that, click on your name at the top right and go +to the settings where you will see the tab to set up your SSH key. + +Note that if the username from your local machine differs from the one in Gerrit, +you might need to set it up in your local ``~/.ssh/config`` file like this: + +.. code-block:: + + Host review.opendev.org + user foo + identityfile /home/foo/.ssh/gerrit + +.. _Launchpad: https://login.launchpad.net/+login +.. _review.opendev.org: https://review.opendev.org/ + +Installing Git Review +--------------------- + +Git Review is a python module that adds a "git review" command that wraps +around the process of sending a commit for review in Gerrit. You need to +install it to be able to send patches for code reviews. + +There are different ways to install git-review, `choose your favorite`_. + +.. _choose your favorite: https://docs.openstack.org/infra/manual/developers.html#install-the-git-review-utility + +Sending a patch for review +-------------------------- + +The process looks a bit like this: + +.. code-block:: bash + + $ git clone https://opendev.org/recordsansible/ara + # or git clone https://github.com/ansible-community/ara + $ cd ara + # Create a new local branch + $ git checkout -b super_cool_feature + # hack on super_cool_feature + $ git commit -a --message="This is my super cool feature" + $ git review + +When you send a commit for review, it'll create a code review request in +Gerrit_ for you. +When that review is created, it will automatically be tested by a variety of +jobs that the ARA maintainers have set up to test every patch that is sent. + +We'll check for things like code quality (pep8/flake8), run unit tests to catch +regressions and we'll also run both integration tests on different operating +systems to make sure everything really works. + +The result of the tests are added as a comment in the review when all of them +are completed. If you're interested in digging into the logs for a particular +test, clicking on the results of the test will take you to console, debug +logs and a built version of ARA's web interface. + +If you get a failed test result and you believe you have fixed the issue, add +the files, amend your commit (``git commit --amend``) and send it for review +once again. This will create a new patchset that will be up for review and +testing. + +To be able to merge a patch, the tests have to come back successful and the +core reviewers must provide their agreement with the patch. + +.. _Gerrit: https://review.opendev.org diff --git a/doc/source/index.rst b/doc/source/index.rst index b405dc46..aea3d082 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -18,6 +18,7 @@ Table of Contents Setting playbook names and labels Recording arbitrary data in playbooks Architecture and workflows + Contributing to ARA .. toctree:: :maxdepth: 1