cloudstack-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From John Burwell <jburw...@basho.com>
Subject Re: Rant: Request for better commit messages
Date Wed, 07 Nov 2012 20:02:29 GMT
Marcus,

To me, it feels like you are hitting on the difference in audience between a commit message
and a ticket.  A commit message describes a technical scope, impact, and reasoning of a particular
revision in the repository which is geared, primarily, towards other developers to understand
the evolution of the codebase.  On the other hand, a ticket describes a problem or enhancement,
and tracks its progress towards resolution and release which is geared towards the entire
community.  Finally, for larger enhancements, it is possible that a ticket would be associated
with multiple commits. 

I agree that we need to be capturing both types of information, but I am proposing that we
capture it separately.
-John

On Nov 7, 2012, at 2:11 PM, Marcus Sorensen <shadowsor@gmail.com> wrote:

> That's great, I'm fine with that if I need to create a bug for everything
> that I know needs to be fixed in the 4.0 branch for example.  The
> header/tag in the commit message may not be something we end up officially
> relying on by any means, but would help me as someone who perhaps maintains
> a specific feature to take a quick look at the logs in master and branch X
> and make sure that everything I thought should be committed ended up in the
> branch, or at least provides me a way to audit. I suppose that's a personal
> thing so I'll just go forward doing that, but it brought up the question as
> to who else might be able to use it or what the official way to tell the
> maintainer of a branch that something needs to be considered for inclusion.
> 
> It seems like several things were missed at different points when 4.0 was
> getting cleaned up, and I don't know if that was due to not following
> procedure or a lack of procedure.
> 
> 
> On Wed, Nov 7, 2012 at 11:31 AM, John Burwell <jburwell@basho.com> wrote:
> 
>> Marcus,
>> 
>> To my mind, it does not seem appropriate for developers to be making
>> release decisions at commit time.  Instead, it feels more appropriate to me
>> that these decisions are captured in a ticket that is referenced from the
>> commit message.  This separation allows the PMO/release management
>> team/community to determine release contents based on the results of review
>> (via Review Board) and testing.  If you feel your change is a high priority
>> and should be in the next release, you would capture that in the ticket.
>> The PMO/release management team/community can then review that decision
>> and comment/adjust as necessary.  A commit message does not permit this
>> type of collaboration.  This separation also seems make the creation of
>> release notes more straightforward as well.
>> 
>> Thanks,
>> -John
>> 
>> On Nov 7, 2012, at 1:16 PM, Marcus Sorensen <shadowsor@gmail.com> wrote:
>> 
>>> Really I just want to make sure that a commit I make that I know needs to
>>> be pushed into the next 4.0 bugfix release gets there. Since someone else
>>> is in charge of maintaining 4.0 and merging bug fixes, I can't do it
>>> myself, and I'm not really sure how it works now. For example, does that
>>> maintainer look through a JIRA report and only merge bugfixes listed
>> there?
>>> 
>>> 
>>> On Wed, Nov 7, 2012 at 11:03 AM, Rohit Yadav <rohit.yadav@citrix.com>
>> wrote:
>>> 
>>>> I'm not sure how (cherry picking, pull based on commit message) this
>> will
>>>> work, but it's good idea to mark the commit with some tag with say
>> branch
>>>> so we always commit on master?
>>>> (Bugfix-for or Branch: <branches> )
>>>> Branch: 4.0, master #(comma separated branch names).
>>>> Bug-id: CLOUDSTACK-xxx
>>>> 
>>>> This may be ambiguous, says some developer did not know if some commit
>>>> would apply for some branch? Another issue is to encourage everyone of
>> us
>>>> to use this convention.
>>>> If we could solve it, that would be great.
>>>> 
>>>> ________________________________________
>>>> From: Marcus Sorensen [shadowsor@gmail.com]
>>>> Sent: Wednesday, November 07, 2012 8:56 PM
>>>> To: cloudstack-dev@incubator.apache.org
>>>> Subject: Re: Rant: Request for better commit messages
>>>> 
>>>> Should we add a line to this commit message, where people can mark
>> whether
>>>> this patch should be considered for the next bugfix release? Or is that
>> all
>>>> handled/tracked through JIRA or some other means? I just thought it
>> would
>>>> be nice for the guy maintaining a release to be able to eventually pull
>> in
>>>> stuff based on the commit messages. It also allows the committers to
>> give
>>>> some sort of indication that commit X is important and needs to go into
>> the
>>>> bugfix.
>>>> 
>>>> For now I'm just adding "Bugfix-for: 4.0" to my commits.
>>>> 
>>>> 
>>>> On Thu, Oct 18, 2012 at 3:59 PM, Marcus Sorensen <shadowsor@gmail.com
>>>>> wrote:
>>>> 
>>>>> Ok, this is now in master, see 9ba7509c70fe82a8ce0b08826d424de452aef1d2
>>>>> 
>>>>> set it up by running the following from your incubator-cloudstack dir:
>>>>> 
>>>>> 'ln -s ../../tools/git/prepare-commit-msg
>> .git/hooks/prepare-commit-msg'
>>>>> 
>>>>> Developers can also optionally commit different prepare-commit-msg
>>>>> scripts for each branch, and the link will point to the one you're on.
>>>>> 
>>>>> On Sun, Oct 14, 2012 at 10:19 AM, Rohit Yadav <rohit.yadav@citrix.com>
>>>>> wrote:
>>>>>> 
>>>>>> On 14-Oct-2012, at 9:18 PM, Marcus Sorensen <shadowsor@gmail.com>
>>>> wrote:
>>>>>> 
>>>>>>> I'm by no means a git guru, but in searching around it didn't
seem
>>>> like
>>>>>>> there was a way to enforce the application of hooks from the
repo
>>>> side.
>>>>>>> I'm not sure we'd want to anyway. I was just going to commit
the file
>>>>> and
>>>>>>> then add instructions on the wiki for people to add it in their
local
>>>>> repo
>>>>>>> config.
>>>>>> 
>>>>>> I think that's fine. Instead of hooks what people can do is add a
>>>> commit
>>>>> template to their local git configuration.
>>>>>> http://git-scm.com/book/en/Customizing-Git-Git-Configuration
>>>>>> 
>>>>>> Checkout commit.template, add following to your ~/.gitconfig:
>>>>>> [commit]
>>>>>> template = ~/.gitmessage
>>>>>> 
>>>>>> And create a ~/.gitmessage like:
>>>>>> #Header: one line explaination
>>>>>> #
>>>>>> #Body of commit message explaining things in more detail, possibly
>>>>> giving some
>>>>>> #background about the issue being fixed, etc. Maybe use bullets:
>>>>>> #  - Write in present tense
>>>>>> #  - Keep text width of commit message within 80 characters.
>>>>>> #
>>>>>> #Use more than one paragraphs, that's is fine.
>>>>>> #
>>>>>> #Reviewed-by: Person or link to review on review.apache.org
>>>>>> #Reported-by: whoever-reported-it, if applicable
>>>>>> #Signed-off-by: Your Name <youremail@yourhost.com>
>>>>>> 
>>>>>> Now every time one does git commit, she will see this in their editor
>>>>> and use this as a reminder to write better commit message.
>>>>>> For example my:
>>>>>> gitconfig:
>>>>> https://github.com/bhaisaab/dotfiles/blob/master/git/gitconfig
>>>>>> gitmessage:
>>>>> https://github.com/bhaisaab/dotfiles/blob/master/git/gitmessage
>>>>>> 
>>>>>> Regards.
>>>>>> 
>>>>>>> On Oct 14, 2012 4:07 AM, "Rohit Yadav" <rohit.yadav@citrix.com>
>>>> wrote:
>>>>>>> 
>>>>>>>> 
>>>>>>>> On 12-Oct-2012, at 10:29 PM, Marcus Sorensen <shadowsor@gmail.com>
>>>>> wrote:
>>>>>>>> 
>>>>>>>>> Sure thing.  A few questions:
>>>>>>>>> 
>>>>>>>>> the "CLOUDSTACK-<BUGID> prefix:" line, should that
be changed to
>>>>>>>>> simply "Bug id:"?
>>>>>>>> 
>>>>>>>> I guess as there are already several commits that follow
>>>>> CLOUDSTACK-BUGID
>>>>>>>> convention, we should continue that.
>>>>>>>> Also, there are commits with bug id's of old jira, like CS-16414
>> etc.
>>>>>>>> 
>>>>>>>>> I'm assuming that if the commit is a bug fix, the
>>>>>>>>> fix will already be described in the summary and detail
of the
>>>> commit.
>>>>>>>>> Or are we looking for something else here other than
a description?
>>>> I
>>>>>>>>> could just see this being redundant, but perhaps I don't
understand
>>>>>>>>> what's being asked for on that line. Should id describe
the bug
>>>> itself
>>>>>>>>> in one line, rather than the bug fix?
>>>>>>>> 
>>>>>>>> Whatever makes sense, I usually write what that commit does
in one
>>>>> line.
>>>>>>>> 
>>>>>>>>> 
>>>>>>>>> I'm also assuming it's ok to add the "Signed-off-by:"
to the
>>>> message.
>>>>>>>>> I realize that some people will have their own configs
that already
>>>> do
>>>>>>>>> this, or be used to using -s to auto-add it to the message,
but
>>>>>>>>> judging by the logs it seems that the majority don't.
So hopefully
>>>>>>>>> this doesn't upset anyone horribly :-) They can always
change their
>>>>>>>>> copy since the hook will need to be manually installed.
>>>>>>>> 
>>>>>>>> I've just put up bunch of guidelines on the wiki, let's take
>> whatever
>>>>>>>> seems good and follow whatever makes sense.
>>>>>>>> My whole intension was to bring up the issue that a short
commit
>>>>> message
>>>>>>>> makes it hard for folks to follow commits.
>>>>>>>> 
>>>>>>>>> Attached is an example commit message generated by the
hook so far.
>>>>>>>> 
>>>>>>>> Cool, I guess you would have to contact someone from ASF
infra to
>> set
>>>>> this
>>>>>>>> up.
>>>>>>>> 
>>>>>>>>> I
>>>>>>>>> left in the default comment message as well, simply because
it
>>>>>>>>> includes a list of what's modified,etc for reference
when typing up
>>>>>>>>> the notes.
>>>>>>>> 
>>>>>>>> --
>>>>>>>> Rohit
>>>>>>>> 
>>>>>>>>> 
>>>>>>>>> On Fri, Oct 12, 2012 at 2:56 AM, Rohit Yadav <
>>>> rohit.yadav@citrix.com>
>>>>>>>> wrote:
>>>>>>>>>> 
>>>>>>>>>> I ported an old wiki from wiki.cloudstack to cwiki.a.o
>>>>>>>>>> 
>>>>>>>> 
>>>>> 
>>>> 
>> https://cwiki.apache.org/confluence/display/CLOUDSTACK/Git#Git-CommitMessages
>>>>>>>>>> 
>>>>>>>>>> Pl. check and edit as needed.
>>>>>>>>>> 
>>>>>>>>>> One more thing, I checked looks like ASF infra guys
have upgraded
>>>>> their
>>>>>>>> review board.
>>>>>>>>>> The bug (
>>>>>>>> 
>>>>> 
>>>> 
>> http://code.google.com/p/reviewboard/issues/detail?id=2690&thanks=2690&ts=1343826104
>>>>> )
>>>>>>>> got fixed so now downloading the diff downloads the actual
uploaded
>>>> git
>>>>>>>> formatted patch.
>>>>>>>>>> 
>>>>>>>>>> On 12-Oct-2012, at 2:42 AM, Marcus Sorensen <shadowsor@gmail.com>
>>>>>>>> wrote:
>>>>>>>>>> 
>>>>>>>>>>> Might be cool if we could make/document git hooks
for a standard
>>>>>>>> message form.
>>>>>>>>>> 
>>>>>>>>>> Marcus it's a good idea, pl. check if we can add
git hooks to ASF
>>>>> repo
>>>>>>>> that would be great.
>>>>>>>>>> 
>>>>>>>>>> Regards.
>>>>>>>>>> 
>>>>>>>>>>> 
>>>>>>>>>>> On Thu, Oct 11, 2012 at 3:05 PM, Wido den Hollander
<
>>>> wido@widodh.nl
>>>>>> 
>>>>>>>> wrote:
>>>>>>>>>>>> 
>>>>>>>>>>>> 
>>>>>>>>>>>> On 10/10/2012 08:50 PM, Noah Slater wrote:
>>>>>>>>>>>>> 
>>>>>>>>>>>>> Perhaps we could document this on the
wiki, as part of a
>> nascent
>>>>>>>> coding
>>>>>>>>>>>>> standards policy?
>>>>>>>>>>>> 
>>>>>>>>>>>> 
>>>>>>>>>>>> I'd say so. We already have a coding convention,
it's just a
>>>> small
>>>>>>>> step to
>>>>>>>>>>>> add a commit convention.
>>>>>>>>>>>> 
>>>>>>>>>>>> I personally like 'clean' GIT repos with
clear commit messages.
>>>>>>>>>>>> 
>>>>>>>>>>>> Wido
>>>>>>>>>>>> 
>>>>>>>>>>>> 
>>>>>>>>>>>>> 
>>>>>>>>>>>>> On Wed, Oct 10, 2012 at 8:01 AM, Rohit
Yadav <
>>>>> rohit.yadav@citrix.com
>>>>>>>>> 
>>>>>>>>>>>>> wrote:
>>>>>>>>>>>>> 
>>>>>>>>>>>>>> Hi folks,
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> With due respect, I would like to
request all the committers
>>>> and
>>>>>>>>>>>>>> contributors to write better commit
message. [0]
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> For example, a good commit message:
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> 
>>>>>>>> 
>>>>> 
>>>> 
>> https://git-wip-us.apache.org/repos/asf?p=incubator-cloudstack.git;a=commit;h=384c03e42578f17432a483d5828aad64175d9c49
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> A good commit message subject should
have something like this
>>>>> with
>>>>>>>> 80
>>>>>>>>>>>>>> chars width:
>>>>>>>>>>>>>> <Header line>: <short log
description>
>>>>>>>>>>>>>> <blank line>
>>>>>>>>>>>>>> <body of commit message, explain
things why, what, how, etc.
>>>>> giving
>>>>>>>>>>>>>> background>
>>>>>>>>>>>>>> <bulleted points help>
>>>>>>>>>>>>>> <blank line>
>>>>>>>>>>>>>> <Reported-by: if it's a bug>
>>>>>>>>>>>>>> <Reviewed-by: if it was reviewed>
>>>>>>>>>>>>>> <Signed-off: turn on signature
in your .gitconfig>
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> This is what we follow on
>>>>>>>>>>>>>> http://git.videolan.org/?p=vlmc.git;a=shortlogand
they are
>>>> crazy
>>>>>>>> about
>>>>>>>>>>>>>> commits and patches, they just don't
accept junk
>>>>>>>>>>>>>> messages, even if code is fine. You
may check, there is no or
>>>> few
>>>>>>>>>>>>>> reverts.
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> When something breaks, I check all
last commits and do a git
>>>> log
>>>>> -p
>>>>>>>>>>>>>> <file>
>>>>>>>>>>>>>> to go through recent changes to a
file, in case I think
>>>> something
>>>>>>>> broke I
>>>>>>>>>>>>>> like to identify the changes that
may have caused it instead
>> of
>>>>>>>> fixing it
>>>>>>>>>>>>>> which may introduce further problems.
I use tig and zsh to
>>>>> regularly
>>>>>>>>>>>>>> follow
>>>>>>>>>>>>>> commits and read commit messages.
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> Also, please fix your editors and
follow coding conventions.
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> [0]
>>>> https://github.com/torvalds/subsurface/blob/master/README(at
>>>>>>>> the
>>>>>>>>>>>>>> end)
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> Regards.
>>>>>>>>>>>>>> PS. I had to email about it as we're
uncool with our git
>> commit
>>>>>>>> habits,
>>>>>>>>>>>>>> we
>>>>>>>>>>>>>> are doing triple or quadruple reverts,
we need to fix our
>>>> habits.
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> 
>>>>>>>> 
>>>>> 
>>>> 
>> https://git-wip-us.apache.org/repos/asf?p=incubator-cloudstack.git;a=commit;h=7bcbae5e91a4cd122d0efa7f2542eab73debb6df
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> 
>>>>>>>> 
>>>>> 
>>>> 
>> https://git-wip-us.apache.org/repos/asf?p=incubator-cloudstack.git;a=commit;h=c49f3beccfcd1257eca1ea06606fb55b3fdf5093
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> 
>>>>>>>> 
>>>>> 
>>>> 
>> https://git-wip-us.apache.org/repos/asf?p=incubator-cloudstack.git;a=commit;h=66daa1a2bc6e86adea265a8a0b8b512756c8f77c
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> 
>>>>>>>> 
>>>>> 
>>>> 
>> https://git-wip-us.apache.org/repos/asf?p=incubator-cloudstack.git;a=commit;h=828fa3389bbe7cd0378c4e55152d671932badca2
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> 
>>>>>>>> 
>>>>> 
>>>> 
>> https://git-wip-us.apache.org/repos/asf?p=incubator-cloudstack.git;a=commit;h=bb7f9ad9774019f4fdb4d72b2e32a36df9c89188
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> 
>>>>>>>> 
>>>>> 
>>>> 
>> https://git-wip-us.apache.org/repos/asf?p=incubator-cloudstack.git;a=commit;h=75e2a1012fccc01c639c7f41be564ac0e32088fb
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> 
>>>>>>>> 
>>>>> 
>>>> 
>> https://git-wip-us.apache.org/repos/asf?p=incubator-cloudstack.git;a=commit;h=5078dff6e76649fbc51e2b9c003fd8e03eef18f3
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> 
>>>>>>>>>>>>>> 
>>>>>>>> 
>>>>> 
>>>> 
>> https://git-wip-us.apache.org/repos/asf?p=incubator-cloudstack.git;a=commit;h=850433240401cd318f1d8d8b0fa2032a60d52c1f
>>>>>>>>>>>>> 
>>>>>>>>>>>>> 
>>>>>>>>>>>>> 
>>>>>>>>>>>>> 
>>>>>>>>>>>>> 
>>>>>>>>>>>> 
>>>>>>>>>> 
>>>>>>>>> <examplecommitmsg.txt>
>>>>>>>> 
>>>>>>>> 
>>>>>> 
>>>>> 
>>>> 
>> 
>> 


Mime
View raw message