[ckan-dev] CHANGELOG for CKAN 2.0

Fri Mar 1 14:15:09 UTC 2013

Hi Sean,

2013/3/1 Sean Hammond <sean.hammond at okfn.org>

> 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 think we should start doing it in the pull requests. I don't know if you
agree, but I guess writing it a few months after the code was written,
whenever we do the release, is too much work (and error prone).

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.
>

I think this is mainly because we a) work on branches inside the main repo,
and; b) consider branches in the main repo to be public, so don't
amend/rebase/change commits. To solve this, IMO, we need to change either
a) or b).

Personally, I've started working on my fork, so I can show some code for
someone, to gather hints/feedback, but also amend/rebase if needed.

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.
>

This is a good point, to give a summary of the discussions that led to the
commit.

But I guess we're OK relying on GitHub issues as well. If they ever get out
of business (or we move to a new tool), we'll probably not only import the
code, but also their issues and pr, to our new home.

Cheers,
Vítor.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.okfn.org/pipermail/ckan-dev/attachments/20130301/80aae844/attachment-0001.html>