Contribution workflow
This is a quick guide on contributing to the development of the DebOps project.
How to contribute via GitHub
If you want to contribute to DebOps using GitHub, you can start by creating
a fork of this repository and
cloning that fork to your local machine. In your local copy of the
repository, add the official DebOps repository
as an upstream
of your fork.
git clone git@github.com:<username>/debops ~/src/github.com/<username>/debops
cd ~/src/github.com/<username>/debops
git remote add upstream https://github.com/debops/debops.git
Managing your local fork
If you already have a local fork, before starting your work, fetch and rebase
the latest changes from the master
branch of the upstream repository.
If you want to work on a different branch, switch to it and do the same.
git checkout master
git fetch upstream
git rebase upstream/master
git push origin master
During development you might notice that the upstream repository has new
commits. In that case you might want to rebase your feature branch on the
latest changes in the master
branch. If you have any pending changes you
don't want to commit yet, you can save them for later using git
stash. After a rebase, you might need to resolve any conflicts manually.
# Save any pending changes
git stash
git checkout master
git fetch upstream
git rebase upstream/master
git push origin master
git checkout new-feature
git rebase master
# Get back stashed changes
git stash pop
Using git with style
Create a new feature branch and start working on your changes. You can commit frequently, or use an interactive mode to commit partial changes later. Try to keep related changes in separate commits, and separate larger code modifications into multiple commits - this helps with finding out the issues using git bisect. Commits signed by a valid GPG key are preferred.
git checkout -b new-feature
# ... work ...
git add -p .
# ... pick changes to commit ...
git commit
Read How to Write a Git Commit Message to learn the best practices about git commit messages.
Rewriting history and squashing commits is frowned upon, because this may make bisecting harder. Small, focused changes are preferable, unless you are creating a completely new feature, for example a new role; in that case putting everything in one commit as a starting point is a reasonable approach.
You can add entries about more visible changes or new features to
CHANGELOG.rst
, but it's not necessary - it will be updated if needed,
before your pull request is merged.
If you notice that you forgot some changes, you can amend your last commit to
include it. If you already pushed your changes to the forked repository on
GitHub, you might need to --force
push your changes again. However, don't
rewrite history in branches that are already pending as pull requests.
# Modify latest commit
git add -p .
git commit --amend
Pushing your changes
When your changes are ready, you can push them to your DebOps fork on GitHub.
git push origin new-feature
After that, go to the upstream DebOps repository page, and create a new pull
request, either against the master
branch, or the stable branch you were
trying to fix. The new pull request will be tested on Travis which might report
errors, and reviewed by DebOps developers, who might request changes. In that
case, you can commit your changes as normal and then push them to your fork on
GitHub, in the same branch. Your pull request will be automatically updated to
reflect new commits.
# ... Fix issues, add new features ...
git add -p .
git commit
git push origin new-feature
After your pull request is merged, you can fetch the new changes in the
master
branch or other branches you worked on, rebase your local clone of
the repository and push them back to your own fork, just as you would with any
other commit from upstream
.
Then, you can start working on another feature or bugfix.
How to test your changes
Once you push your contribution, Travis CI will run a first round of tests, mostly related to linting and syntax checking, then will promptly reject your contribution for the most pedantic reasons imaginable.
In order to avoid this awkward scenario, you can (and should) run make test yourself!
See the Testing guide for more information on installing the tools required and making the most out of the test suite.
Happy hacking!