A step by step contribution example¶
The process to contribute to Alignak is quite simple. However, depending on what you are planning to do, the most efficient way to do it may vary.
Very simple fix with Github¶
If you have a very small to do (typo, doc, one file commit), you’d better use GitHub. You can click edit in the Alignak repository. It will fork the repository for you and let you edit the file through the Web interface. Once you picked a good commit message (see below for commit message habits) you can push it in a new branch (see below for branch name habits). Finally, you can create a new pull request to the Alignak repository (still with GitHub UI)
Checkout new branch¶
Once you have forked the repository and added remote (see above) you can start a new branch
git checkout -b Add_ponies_and_rainbows
Here your new branch is
Good habits is to name the branch as:
fix-#123for a branch fixing the issue #123.
featurefor a branch implementing a new feature
You can now start editing the files…
Running the same analysis as the one that are executed during a Travis build is an easy stuff. Run the following script in the repository main directory:
# Static code analysis # -- pycodestyle (former pep8) pycodestyle --max-line-length=100 --exclude='*.pyc,carboniface.py' alignak/* # -- pylint pylint --rcfile=.pylintrc -r no alignak # -- pep257 pep257 --select=D300 alignak
Some good links about Python code style:
The dev directory of the repository includes several useful scripts to run Alignak daemons on your development platform. The scripts names are self explanatory and the scripts are commented.
Installing Alignak and its default configuration will create an environment almost identical to the one you will find on your production server. See the how it works chapter for more information.
Before committing (unless you know that you are pushing unfinished stuff) you should create or update some tests. Whether you fix a bug or add a new feature you need to add some test cases.
The Alignak test environment is :ref:`described in details here <contributing/testing>`_.
An example to run the whole test suite:
cd tests pytest --verbose --durations=10 --no-print-logs --cov=alignak --cov-config .coveragerc test_*.py # A more simple test run (without verbose and code coverage) pytest test_*.py # A single test pytest test_my_tests.py
If you have enabled Travis on your fork (recommended) you will receive Travis notifications about the tests results once you pushed some commits to your repository. Else you should browse the Travis builds on the Travis CI.
You should be ready to commit now, all new files and modified files are added in “stage”. If you look at the commit tree, you can notice more or less a pattern in commit message
Enh|Fix|Add: <Generic word to describe> - <Specific word to describe>
Enh: Tests - Clean unused imports
This is not a mandatory format to write commit. If you want to do it differently it’s fine. Always keep in mind that a commit message has to be clear enough. Message like “fix”, “try1”, “update”, “clean” are not really relevant to understand what’s in the commit.
Create pull request¶
You feel like your fix / new feature is ready to be merged upstream? It is time to create a pull request. The pull request is the entry point for Alignak team’s review process.
Keep in mind that we are humans and we usually are doing more that one thing at a time. So the clearer the pull request is the quicker it will be merged Here are some hints to help reviewers
* Explain the issue you encountered, and how you fixed it (short description) * Add test cases in the main commit (better) or in a separate commit * Link any GitHub issue it is related to (if you fix an issue for example) * Mention any limitations of your implementation * Mention any removal of supported feature
If you run the tests previously you should see that Travis managed to build successfully. If not you will get an email from the Travis engine to informa about the tests results.
No pull request will be merged upstream until all Travis tests pass and until one of the reviewer will accept the Pull Request. Reviewers may not look at your pull request if the build is broken.
You don’t need such details for a typo / doc fix.