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 …
We have just released diecutter 0.5, which introduces support of remote templates. Let's explain why it does matter...
Support of remote templates is the major feature of the 0.5 release.
Keep in mind that the current "remote templates" implementation is experimental. It is quite slow …
Here are the slides of a lightning-talk performed at DjangoCon Europe, 2013, Warsaw:
This talk is related to the article published before: Unit test your Django views.
A Python decorator is, basically, a function that take a function as argument and return a function. This is a powerful feature. But it has some drawbacks:
How to test view decorators of Django applications? Here are some tips.
In a post before, I recommended to avoid decorating views in place (i.e. not in views.py). Once decorators and views are separated, we can unit test the views. That was the topic of the post before …
Here at Novapost, we have quite large Django projects. Big projects mean big maintenance. Hopefully, those projects are covered by tests. Thousands of tests. We are quite proud of this fact. Tests save our lives. But we also have some worries and need to improve... Here is our testing challenge …