[ckan-dev] CHANGELOG for CKAN 2.0

Fri Mar 1 10:57:14 UTC 2013

Hey all,

I've done a first stab at a 2.0 changelog in this pr:

https://github.com/okfn/ckan/pull/513

I doubt it covers everything but I think I got most of the features.
I've made no attempt to list bugs fixed as that would be hopeless.

Could each of you take a quick look over this and let me know anything I
missed or got wrong? I think this is worth a few mins of everyone's time
as the changelog is useful for users and will also be useful for us e.g.
to see what undocumented features there are and to see what should go
into 2.0 release blog posts or features pages.

I've got a bunch of unanswered questions in the pr description if anyone
could answer any of them it'd save me a bit of time.

About the changelog file, it currently says in our coding standards that
it should be updated before merging into master, but none of us ever
remember to do this. I was thinking about giving up on this and dropping
it from our guidelines? The reality is that someone updates it before
the release.

I'm not sure what the best way to update the changelog before a release
is. Adria, do you have any tricks? git log ckan-1.8..master is 24,000
lines long (that's just the commit messages, not the diffs), so scanning
through that is hopeless.

I found that looking at closed pull requests on github was quite
efficient and since everything is supposed to go through a pr, in theory
that should work.

(The other thing I did was write a script to find all the three- and
four-digit numbers in the 1.8..master commit logs and print them out as
trac and github issues urls, and piped that to firefox tabs.)

This also touches on our commit logs which are a bit rubbish. The three
main problems here seem to be:

1. Lots of noise, we tend to make a lot of small commits for the same
feature, and also have lots of merge commits, etc. It might not be that
easy to raise our game here though as we'd need to start having wip
branches and rebasing or something. I'm open to suggestions though and I
know Linux would deride our current practices.

2. Many of the commit messages are not very informative. This I feel we
can improve on easily and it's covered in our contributing file already.
They should have:

- Short summary in first line
- If necessary further lines saying why you did the change and
contrasting the new behaviour with the previous

My other bugbear about this is that any info that is necessary to
understand this commit should be copied into the commit message itself,
Not saying you have to copy-paste entire tickets etc, just anything
crucial. It's bad for git logs to rely on external sources like trac or
github issues or pull requests (which I don't trust to still exist in
the future) or google docs etc.

3. Not everyone follows the crucially important advice to use the
imperative present tense! ;)