================== Contribution guide ================== .. note:: Except where otherwise indicated in a given source file, all original contributions to Avocado are licensed under the GNU General Public License version 2 `(GPLv2) `_ or any later version. By contributing you agree with: a) our code of conduct; b) that these contributions are your own (or approved by your employer), and c) you grant a full, complete, irrevocable copyright license to all users and developers of the Run-perf project, present and future, pursuant to the license of the project. Generally one should follow the usual principles known in the open source projects like mentioned in http://www.contribution-guide.org/, still allow me to explicitly mention the most useful advices or specifics of this project. First of all **Always assume good intentions**. Reporting Bugs/Enhancments ========================== Please use the `Issues `_ tab on github to report a bug or suggest an enhancement, there are templates that should simplify the process while making sure all important information are stored for the future reference or reproducibility. First time contribution ======================= .. _clone-and-deploy: Clone and deploy ---------------- Run-perf is a Python3 project, the simplest way to start hacking on it is to:: git clone https://github.com/distributed-system-analysis/run-perf.git cd run-perf python3 setup.py develop --user .. note:: you might need to add `~/.local/bin` to your bash `PATH` environment to make the scripts available in your environment. Which creates an `egg link` under the ``~/.local/lib/python3*/site-packages/`` directory, which makes python to use the libraries in your clonned directory instead of the system ones. This means any change to your sources will be propagated to any new execution for your user. Develop your feature -------------------- We are using github pull request to accept changes, the usual workflow is: 1. go to https://github.com/distributed-system-analysis/run-perf 2. on the right side click ``fork`` and select under which organization you intend to clone it. 3. add this fork to your local git by ``git remote add $name https://github.com/$name/run-perf`` (replacing the `$name` with your github username/organization) 4. checkout a new branch by ``git checkout -b $headline`` (replacing the `$headline` with a suitable short description of what you intend to do) 5. develop your code; use comments and docstrings; don't forget documentation and tests. 6. prepare the patches using ``git commit -as``; don't forget to add new files via ``git add``, use sensible commit messages and split the patches to make reviewing easier (usually if you need to use `and` or `also` in the commit message it's time to split the commit). Allow me to suggest ``git cola`` for that. 7. commit them to your repo via ``git push $name HEAD`` optionally followed by ``-f`` to force-override the changes (again, replace `$name` with you) #. go to https://github.com/distributed-system-analysis/run-perf where a new ``Compare & pull request`` button listing your new branch should appear (alternatively you can go to your fork, select your branch and use the ``Pull request`` button from there. #. describe your changes, consider including your motivation and examples and create the PR. #. wait for the CI to finish and address all possible issues (or directly ask someone for a help, failing PRs will **not** be reviewed). #. wait for a review, in case of a ``request for a change`` address all issues (even if just as a comment explaining why not to change that) and repeat steps 5-7 using the ``-f`` to override the changes when committing and do include a comment describing the changes you made. Reviewer process ================ **Anyone is welcome to review the patches**, no affiliation to runperf or any organization is needed, but in the end one needs to gain an ack from someone with a write access to the repo. Having an extra review can speedup the process, though. .. warning:: Developer is responsible to conform to the contibution guide, but it's the **reviewer** who **is responsible** for the code that is being merged. #. Check the CI status, merging anything that would break CI is not allowed #. Check the ``Signed-off`` line is present in all commits #. Check the license header and copyright of the new files #. Review all commit messages, see whether they tell a complete story #. Thoroughly review all individual changes, test them even one by one if in doubt as each commit has to be applicable standalone (to make reverts easier) #. Check there are no regressions introduced #. Commit the code upstream using ``git merge -S`` to sign the merge commit using their gpg signature. During this process take notes and add them to your review. It's better to be verbose to avoid unnecessary actions or harm, we don't see each others and one incorrect sentence can ruin one's day.