Contribution

Merge Requests

We would be happy to get new contributors. Feel free to open issues and send us merge requests.

Python Style Guide

We’re trying to be consistent with PEP 0008 - Style Guide for Python.

However, please note we don’t follow the following rules:

  • E221: We try to align variable assignments nicely to improve readability
  • E501: The maximum line length of 79 chars is not very nice for readability

Please also think about the format of your data structures, especially for extendible ones. For example:

# This works.
foo = ['a', 'b', 'c']

# But this is much better.
bar = [
    'a',
    'b',
    'c',
]

If you’re expanding both lists and you make a diff, you’ll notice that the changes of foo are much harder to tell than the changes of bar. So try to use multiple lines instead of only single ones and make sure you always add a comma to the last element as well.

There are great tools out there which can help you to test against PEP 0008 or even automatically reformat your code. The ones we’re using are:

If you’re using the Sublime Text plugin, make sure you set the following package options:

{
    "ignore": [
        "E221",
        "E501",
    ],
}

Branches

Please note that we use Vincent Driessen’s gitflow model, so make sure you create proper feature branches.

All branches must be properly named, which means:

  • develop is the bleeding-edge development branch
  • master is the latest stable branch
  • hotfix-* branches are hotfix branches
  • release-* branches are release branches

Feature branches have no fix naming scheme, though their name should describe the feature accordingly.

Tags

We’re using semantic versioning, which means:

  • version tags are named v{MAJOR}.{MINOR}.{BUGFIX}
  • release branches are named release-{MAJOR}.{MINOR}

Commit messages

Also make sure you use proper commit messages and prefix them with:

  • FEATURE: Added new foobar feature
  • BUGFIX: Fixed foobar bug
  • DOCS: Updated the documentation for foobar
  • REFACTOR: Refactored code of foobar which didn’t affect the meaning of the code itself
  • STYLE: Updated code style of foobar
  • TEST: Added new Travis CI test for foobar

If there’s an issue available (especially for bugs) make sure you mention the issue number it in the git commit message as well:

  • FEATURE #42: Added new foobar feature
  • BUGFIX #42: Fixed foobar bug

Creating a changelog

The changelog can automatically be created from the git commit messages. Just checkout the git repository and run the following Python script:

./changelog.py COMMIT

A changelog will be created from the first till the commit you specified as COMMIT. Please note that you can use any git reference for COMMIT (e.g. HEAD, a SHA sum, branches, tags).

The changelog will be printed to standard out. However, you can easily redirect it if you’re creating a new release:

./changelog.py COMMIT >CHANGELOG.rst

Just make sure you replace the COMMIT heading in CHANGELOG.rst with a proper release version before commiting it.

Creating a new release

To create a new ansibleci release make sure the new version meets the following requirements:

  • a release branch or a hotfix branch is existing
  • everything is checked in
  • all classes and methods are described / documented
  • all tests are documented in docs/built-in-tests.rst
  • the new release is tested properly
  • the PyPI setup.py script is updated with the new targeted version
  • the docs conf.py script is updated with the new targeted version
  • a new changelog is created

To test the docs you can either let them build on Read the Docs or build them locally:

pip install sphinx
cd docs/
make html

Then create a new ansibleci distribution and upload it to the test PyPI server:

./setup.py sdist upload -r https://testpypi.python.org/pypi

Test the new package version by installing it via pip:

pip install -i https://testpypi.python.org/pypi ansibleci=={version}

More about PyPI packaging can be found on packaging.python.org and diveinto.org. The basic usage of the test PyPI server can be found in TestPyPI on wiki.python.org.

If everything worked properly, create the new git tag / release and upload the package to the live PyPI server:

# Merge release branch into master.
git checkout master
git merge --no-ff release-{MAJOR}.{MINOR}   # or hotfix-*
git push

# Delete release branch.
git branch -d release-{MAJOR}.{MINOR}       # or hotfix-*
git push -u origin :release-{MAJOR}.{MINOR} # or hotfix-*

# Tag release.
git tag -a [-s -u {GPG key ID} v{MAJOR}.{MINOR}.{BUGFIX}]
git push -u origin v{MAJOR}.{MINOR}.{BUGFIX}

# Create and upload new PyPI release.
./setup.py sdist upload

The docs will be generated automatically.