Sounds ok since you have only one commiter.
But the git history becomes unnecessarily complex since several features are coded at the same time or when features require a base branch merge.
So here is a …
At PeopleDoc, in our development workflow, many questions came about CHANGELOG: what to put in CHANGELOG? How to maintain CHANGELOG and make sure it stays up to date? How do releases affect CHANGELOG? ...
In this article, I'll try to share my experience on the topic, as a base for discussions, and perhaps as a reference for implementations.
I expect CHANGELOG to explain a project's history to users (humans! not bots).
Changelog ========= This document describes changes between each past release. For information about future releases, check `milestones`_ and :doc:`/about/vision`. 0.2 (unreleased) ---------------- - Nothing changed yet. 0.1.1 (2014-04-09) ------------------ Fixes around distribution of release 0.1. - Bug #12 - piecutter archive on PyPI was missing many files. 0.1 (2014-04-08) ---------------- Initial release. - Feature #6 - Imported stuff from diecutter: loaders, writers, resources and engines. .. rubric:: Notes & references .. target-notes:: .. _`milestones`: https://github.com/diecutter/piecutter/issues/milestones
Of course, this CHANGELOG could be improved. As an example with some links to the bugtracker for each feature/bugfix. Or with additional information about how to upgrade from one version to another. But you get the idea: the content is quite simple, explains briefly the changes, and is human-readable. It is not a commit history.
How to maintain such a CHANGELOG?
At first, I tried to update the CHANGELOG inside the topic branches, before they are merged, so that I was able to merge the topic branch using Github's "merge pull-request" button. This is easy and cool... when you are the only contributor!
When you work in a team, or receive pull-requests from community, maintaining CHANGELOG in topic branches becomes harder:
As a consequence, pull-requests take longer to be merged because of some weird issues such as CHANGELOG, typos or wording.
Of course it is nice if the pull-request meets your quality requirements and you do not need to edit the code. But communication with the contributor takes time and sometimes it introduces excessive latency compared to the value of the changes. What a waste of energy!
Now, I merge pull-requests manually, and maintain CHANGELOG in the merge commit:
That way, the CHANGELOG in master is always up to date. It is quick and really clean.
As a bonus, having a merge commit with a smart message makes the git log --first-parent really useful: it is the fastest, easiest and safest recipe I know (at the moment) to keep the Git history readable. But that's another story I already mentioned in git history matters .
So, CHANGELOG in master is always up to date. Now let's do a release!
In the example above, the latest "in-development" release has "unreleased" instead of a date. In Python projects, I use zest.releaser  to update the date, upgrade version numbers and push the code on both PyPI and Github.
Since the CHANGELOG is ok, this is just one command:
In most cases, fullrelease --no-input is fine too! It is faster :)
I haven't tried this recipe yet, but I think this is the next step...
Since the release is just one command, what about automating the release process? This could be a great step on the road to continuous deployment!
I think I will try the following scenario:
Releases are not automatically published for each commit! Releases are (automatically) triggered after a (manual) merge/push in master branch. As a human, you keep control on the merge operation. The idea is that the value lives in the merge which involves human review, then other tasks can be performed by bots.
Of course, this release policy has to be explained in documentation (in CHANGELOG itself?).
And it requires to care about what is merged into master branch... Because a broken master would mean a broken release. But I believe this is a good philosophy: make sure the master branch is stable!
See you when I try it ;)
In many projects, core-committers chose a Git workflow: branching policy, best practices for commit messages, pull-request management... About the latter, some people recommend rewriting Git history via rebases, squashes, patches... As an example, let's quote Django documentation about "Handling pull-requests" :
Use git rebase -i and git commit --amend to …
I like to have a nice commit list mainly because I am using this commit list to generate release CHANGELOG between two changelogs.
First of all configure your favorite editor:
git config --global core.editor emacs
or you might want to use vim:
git config --global core.editor vim …
This article tries to point out a potential problem with rebasing, and how to solve it with merges. Examples use Git, but the story could be adapted to other DVCS, like Mercurial with rebase extension.
master: C0---C1---C2 \ topic: C3
Basic rebasing git checkout topic && git rebase master:
If, during a merge, you have to resolve conflicts on files you didn't change in your branch, then you maybe merged the wrong way. Yes, during a merge, direction matters. Here are some tips to figure it out and avoid some merge nightmares.