Commit Digest Guidelines was: commit path sorting for Git and guidelines

[Marco Krohn]

On Sun, Jan 16, 2011 at 3:04 PM, Alexander van Loon
<a.vanloon at alexandervanloon.nl> wrote:

> Can everyone take a look at http://community.kde.org/Commit_Digest_Guidelines and change them if necessary? If I
> remember correctly, Danny said on the mailing list he would take a look at them, but so far I’m the only one who has ever
> edited them. I’d especially like some input on the question of what we do with commits mentioning that a branch is merged,
> which occur often since the Git migration. See the Uncertain section on the wiki page.

I have read the guidelines and as mentioned before I completely agree
with you changes and additions - thanks a lot! In my opinion you can
remove the "Original Inclusion Guidelines" section. Some comments to
"uncertain cases" list:

Excerpt from http://community.kde.org/Commit_Digest_Guidelines
----------------
1) Commits which change the contents of the files called NEWS,
AUTHORS, Changelog, README and TODO should be excluded.
2) Commits which increase the version number (for alpha and beta
versions) should be excluded, unless it's for a new release (or not
for new releases either? comment please?).
3) What do we with reverts of commits? For example removal of code (is
that considered refactoring which should be removed according to
guidelines), or more specific commits which remove a feature because
the feature is not considered ready for the next stable release?
4) What do we do with the commits which often occur since the
migration to Git which mention a branch merge?
----------------

IMHO all four points should be moved to the "specific guidelines" section.
(1), (2) for certain
(3) is not necessarily a type of "refactoring", actually in most cases
it will not be. A revert most often happens if the (recent addtions)
of someone else caused problems in some other areas. Thus, it is more
a revert of a recently introduced bug, which is IMHO not worth an
inclusion in the CD (as almost no one will know about the bug and thus
it is not interesting)
(4) All messages that are like "Merge branch 'master' into
libs-tosrefactor-zagge" fail in my humble opinion the most important
inclusion criteria: "being interesting".

By the way: when I wrote the initial set of inclusion guidelines I
considered all commits that fix a bug interesting. I am not sure this
is general consensus, as Danny once mentioned the 5% rule (i.e., max.
5% of all commits should be included). If this is the case then I
suggestion to change

"fix a bug, are an optimization or add a feature (for the user); this
is in particular the case when there is a "broken box" symbol in the
lower right corner of the message,"

to something which emphasizes the importance of the bug; and also
include the "5% rule" as a general guideline.


> As far as I know commits made to a branch will reach the review first, followed by a branch merge last.

I think so.

> If I’m correct these branches are clones of the trunk or head, and they’re some kind of isolation cell were developers can work on features
> without disrupting the stability of head.

My understanding as well.

> Considering that the interesting commits mentioning the new features being worked
> on in a certain branch are supposed to be included already, and that the banch merge commits are very nondescriptive and
> merely tells us that the features are from then on part of head, I don’t think we should include them, or should we?

I fully agree.

Best regards,
  Marco