Home

Developer guide

The goal of this guide is to help you to contribute to Alignak. We give info about files and folders of repository and procedure to commit.

Structure of files and folders

The most important to know

alignak folder of python library Alignak
bin folder for the distro packaging (man pages, systemd scripts, ...)
dev folder that contains some useful scripts to run alignak
doc folder : content generated with the following command

rm -rf doc/source/reference/* && sphinx-apidoc -o doc/source/reference/ alignak/

Don't forget to run this command if you update docstring in Alignak.
etc folder for the default shipped configuration
tests folder where for unit tests, used to maintain Alignak in a good health ;)
tests_integ folder for nitegration tests. Tests that start one or more daemons to check overall behavior.

other less important

setup.py file used to install Alignak (directly or through pip)
.travis.yml configuration for the Travis CI tests nd deployments

Packaging

The application packaging is done during the Travis CI build process... here is an abstract.

Python packaging

# Set Alignak version in alignak/version.py
VERSION = "1.1.0rc0"

# In alignak repo main directory:
python setup.py sdist

# Upload the package to the test pypi
twine upload --repository-url https://test.pypi.org/legacy/ dist/alignak-1.1.0rc0.tar.gz

# Test packaging
sudo pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple alignak==1.1.0rc0
...
...
Successfully installed CherryPy-15.0.0 alignak-1.1.0b0 backports.functools-lru-cache-1.5 certifi-2018.4.16 chardet-3.0.4 cheroot-6.3.1 docopt-0.6.2 idna-2.6 importlib-1.0.4 more-itertools-4.1.0 numpy-1.14.3 portend-2.2 psutil-5.4.5 pytz-2018.4 requests-2.18.4 setproctitle-1.1.10 six-1.11.0 tempora-1.11 termcolor-1.1.0 ujson-1.35 urllib3-1.22

# Check files copy
ls -al /usr/local/etc/alignak
# Contains the default configuration files (same as the etc repo directory)

Distro packaging

Using the fpm tool, see https://github.com/jordansissel/fpm

# Installing
sudo apt-get install ruby ruby-dev rubygems build-essential
sudo gem install --no-ri --no-rdoc fpm

# Packaging (not always useful...)
sudo pip install virtualenv virtualenv-tools
sudo pip install --upgrade distribute

# Get Alignak repo
git clone http://github.com/alignak-monitoring/alignak
cd alignak
# Build package and update bintray json file
./package.sh branch_name python_version package_type
# package.sh script is commented for all command line options
# - branch name: master, develop, other...
# - python version:
#   2.7, 3.5 (when called from the Travis build, it is the most recent python 3 version)
# - package type:
#   deb (default), rpm, ...

Repository

Branches

There is a minimal number of branches in the repository to be simple:

master this branch is the branch of the current stable release
develop this branch is the branch where to add new features for the next stable release

Rule to commit

Nobody commits code directly in the main branches of the official repository (core developers included)! We work only with pull requests (PR).

A pull request is:

a branch on a forked repository of alignak (in this case, a forked version in your github repository)
one feature or one fix only. If you have many features / fixes, create one pull request for each
some tests (of course) for the fix or feature
one (or max 2) commits for the fix/feature and tests to keep the git history simple

When the pull request is created, one of the core developers will review the pull request.

Possible actions when the pull request has been reviewed:

it's ok, nice ;)
- core developper accept the pull request and merges it in the official repository (develop branch)
it's not ok, core developper add some comments in the pull request to inform the problem. This is some possible reasons:
- tests not ok (each pull request run tests and you can see if your pull request not create problems)
- tests are missing
- not aggree with the code (syntax, implementation...)

Commands to commit / pull request

prepare your local repository

clone the official repository

git clone [email protected]:Alignak-monitoring/alignak.git

in github interface fork the official repository in your account space (for example, we use myspace)

TODO: screenshot

add your forked repository in local git

git remote add myalignak [email protected]:myspace/alignak.git

get all branches of your forker repository

git fetch myalignak

begin to work

Be sure you are in branch develop

git checkout develop

create a new branch in local for you feature or fix, branched of the develop branch :

git branch nameofyourfeatureorfix

go in this branch

git checkout nameofyourfeatureofrix

write your code + tests ;)

Let's go: think, write, think, write, think, write ^^

Add your name

Add your name in file /AUTHORS if it is not in this. It's the list of persons have contributed to the project

6, check if your code is ok (like indentation...)

pep8 --max-line-length=100 --ignore=E303,E302,E301,E241 --exclude='.pyc' alignak/

commit your changes

git add filex1 filex2 git commit -m "message for the commit"

when finished, push your branch in your forked repository

git push myalignak nameofyourfeatureorfix nameofyourfeatureorfix

Go in github and gituhp propose you to create pull request from your branch and the develop branch of the official Alignak repository
If you want to create another feature/fix, go to 1. ;)

How I can add another commit after the pull request has been created?

Don't be affraid, It's very simple:

in your local repository, go in the branch of your pull request

git checkout nameofyourfeatureoffix

make the changes and commit