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

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)

  8. 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.

  9. describe your changes, consider including your motivation and examples and create the PR.

  10. wait for the CI to finish and address all possible issues (or directly ask someone for a help, failing PRs will not be reviewed).

  11. 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.

  1. Check the CI status, merging anything that would break CI is not allowed

  2. Check the Signed-off line is present in all commits

  3. Check the license header and copyright of the new files

  4. Review all commit messages, see whether they tell a complete story

  5. 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)

  6. Check there are no regressions introduced

  7. 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.