Skip to content
Frédéric MOHIER edited this page Aug 16, 2018 · 14 revisions

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

  1. clone the official repository

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

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

TODO: screenshot

  1. add your forked repository in local git

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

  1. get all branches of your forker repository

git fetch myalignak

begin to work

  1. Be sure you are in branch develop

git checkout develop

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

git branch nameofyourfeatureorfix

  1. go in this branch

git checkout nameofyourfeatureofrix

  1. write your code + tests ;)

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

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

  1. commit your changes

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

  1. when finished, push your branch in your forked repository

git push myalignak nameofyourfeatureorfix nameofyourfeatureorfix

  1. Go in github and gituhp propose you to create pull request from your branch and the develop branch of the official Alignak repository

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

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

git checkout nameofyourfeatureoffix

  1. make the changes and commit

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

  1. update your local branch in your forked repository

git push myalignak nameofyourfeatureoffix:nameofyourfeatureoffix

  1. your new commit is automatically added in the pull request

Need more help, chat with us

We have multiple ways to chat:

  • IRC, channel #alignak on freenode
  • mailing list developers
  • gitter on github
  • github issues for questions or new features / fixes