Git-related guidelines

The following guidelines are a description of the workflows that are mandatory for the maintenance of any git repository of the pyeve organization.

Though it is still a draft.

General considerations

The git history shall preserve as much information as possible, e.g. about merge events, that can be explored with git log --graph --decorate --all --oneline
"Now is better than never." is imperative regarding changelogs and authors lists.
The changelog shall be wrapped at 80 characters for readability on common devices.

The following placeholders are used below:

<pr_id> is the numerical identifier of a pull request
<remote> is the name of the authorative remote repository on github.com
- usually upstream or origin

There is a consent among the reviewers to proceed.
- One shall of course review own proposed changes, but obviously one's voice doesn't count in the review process.
Make sure to work on the up-to-date master branch: git checkout master && git pull <remote> master
Fetch the desired pull request's changes: git fetch <remote> pull/<pr_id>/head:pull_<pr_id>
Check it out: git checkout pull_<pr_id>
Align it with the state of the master branch: git rebase master
Check that there is a descriptive note including references to relevant issues in the "Unreleased" section of the changelog and that all involved contributors are mentioned in the authors list. Mind to commit adjustments.
Push the current state to trigger jobs on the CI: git push <remote> pull_<pr_id>. Depending on the changes and available interpreters, local tests may be sufficient or even better.
Actually merge and publish the changes: git checkout master && git merge --no-ff pull_<pr_id> && git push <remote> master
If applicable, proceed with "Backporting fixes" below. If so, you may repeat this flow with other pull requests before.

All related issues and pull requests in the issue tracker are closed.
Make sure to work on the up-to-date master branch: git checkout master && git pull <remote> master
Update the "Unreleased" section in the changelog and the version in setup.py.
Commit and publish these changes on github.com: git commit -a -m "Bumps to version <major>.<minor>" && git push <remote> master
Create a git tag and publish it: git tag <major>.<minor> && git push <remote> <major>.<minor>
Publish the new version on the PyPI: python setup.py sdist
Add a new "Unreleased" section in the changelog, commit and publish this on master.
Create a new branch for the minor release and publish it: git checkout -b <major>.<minor>.x && git push --set-upstream <remote> <major>.<minor>.x

You have an ordered list of commit hashes (<hash>) that need to be backported for a minor version.
Work on an up-to-date branch for that minor version: git checkout <major>.<minor>.x && git pull <remote> <major>.<minor>.x
Apply the commits: git cherry-pick <hash>...
Run tests and update the changelog.
Publish the backported changes: git push <remote> <major>.<minor>.x

All related issues and pull requests in the issue tracker are closed.
Work on an up-to-date branch for the related minor version: git checkout <major>.<minor>.x && git pull <remote> <major>.<minor>.x
Update the "Unreleased" section in the changelog and the version in setup.py.
Commit and publish these changes on github.com: git commit -a -m "Bumps to version <major>.<minor>" && git push <remote> <major>.<minor>.x
Create a git tag and publish it: git tag <major>.<minor>.<micro> && git push <remote> <major>.<minor>.<micro>
Publish the new version on the PyPI: python setup.py sdist
Copy the changelog section of this release to the changelog in the master branch, commit and publish the result to <remote>.