Contribution

Merge Requests

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

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

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

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 sdist upload

The docs will be generated automatically.