Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [platform-ui-dev] Commit conventions

Update my 0.5 vote to +1 for the updated proposal. :-)

Am 18.11.2015 12:04 vorm. schrieb "Andrey Loskutov" <loskutov@xxxxxx>:
Hi all,

thanks for replying, see my comments to your feedback below!
So far we got some valuable feedback and since it was very positive, I would like to summarize and update the proposal.

On Monday 16 November 2015 15:40 Andrey Loskutov wrote:

> The proposal is short: change Platform UI commit guidelines to follow guidelines from EGit/JGit, see [5].
>
> This would imply:
> 1) A commit subject (first line) must not repeat bugzilla bug title but must be a concise change summary.
> 2) Trivial commits do not require to point to any bug, or other way around: commits without associated bug are possible.
> 3) Bug: <number> footer line is used instead of the "<Bug number and title from bugzilla>" subject to allow gerrit connect commits to bugzilla.

 On Monday 16 November 2015 16:08 Lars Vogel wrote:

> I think this is not a Platform UI specific issue, it is the convention
> for the whole platform and / or for the whole top-level Eclipse
> project. I think, if we want to simplify that, we need to change the
> rules for the top-level project, as more and more people work
> cross-project.

I'm always trying to be as concrete as I can and get things done if I can. My primary goal of this proposal is Platform UI project.
I think we (Platform UI as a team) can decide for ourselves which commit conventions we would like to have and we do not depend on PMC decision here.

> Dani as project lead for the Eclipse platform and Eclipse top-level
> project would need to decide that. Or bring it to the Eclipse
> top-level PMC.

But of course it would be helpful for other teams if the Dani or you could bring the updated proposal to the PMC as a recommendation for other projects with old or outdated guidelines.

> A weak +1 from my side for this simplification.

On Tuesday 17 November 2015 15:08 Stefan Xenos wrote:

> I really like having the bug number in the subject, since the bug has the
> most useful context for the change. I find I use the bug number more than
> anything else in the commit comment, and the most important information
> should be right up front. So -1 for removing the bug number from the
> subject.
>
> However, changing the subjects from being a copy of the bug description to
> being a description of the change makes complete sense to me.
>
> If we're going to say that bug descriptions are not mandatory, we should
> have clear guidance as to when they are or aren't required. I'd propose
> that if the patch contains no functional changes (it only changes
> whitespace and comments) no bug should be necessary. If it contains any
> functional changes a bug should be necessary. That would let us update
> copyright headers, reformat files, remove trailing whitespace, etc. without
> a bug number... but would mean a bug would always be present if there's
> ever anything to discuss about the change.

I count this as +1 and a basis for updated proposal (follows).

On Tuesday 17 November 2015 11:11 Paul Webster wrote:

> +1.  I find the whole bug description in the subject useful, but as long as
> the bug prefix was still there, "Bug 37664" that would be good enough for
> me.

I count this as +1 for updated proposal.

On Tuesday 17 November 2015 17:15 Daniel Megert wrote:

> +1, unless that additional change is big enough to deserve a separate bug
> report.

I count this as +1 for updated proposal.

So we have 4 answers with 3 clear +1 for Stefan's updated proposal and a "weak" one for original proposal.
Also count +1 from me to the updated proposal and we have +4.5 for the change.

I would like to provide here an updated formal proposal which we could put in the wiki:

1) In general, each commit with functional code changes requires a bug entry. Non functional commits changing lot of code also require a bug entry. A bug must always be present if there's ever anything to discuss about the change.
2) If the commit contains no functional changes or the change is fairly small and trivial it does not require a bug. Example: converting an old style "for" loop to modern "foreach" loop, white space changes, formatting, comments in one or few files.
3) A commit subject (first line) must start with the "Bug <bug number> - " prefix followed by a change summary. This prefix is not needed for trivial commits not requiring a bug entry.
4) The change summary should be short, clear and concise description about the change, should start with capital letter and should not end with a dot. A blank line separates it from the body of the message.
5) The body of the commit message should be more detailed explanatory text (if necessary), describing the change.
6) The footer of the commit is separated with a blank line from the message and contain "Change-Id:", "Signed-off-by:" and optional "CQ:" fields:
 - A Gerrit "Change-Id" is required for all changes pushed to Gerrit (to enable pushing new patchsets for the same change), it should be added in the format shown below. Use the Gerrit commit message hook or EGit to add the Change-Id.
 - A "Signed-off-by" can be added at the end of the commit message, the email must be the one used to sign CLA (see example below).
 - If a Contribution Questionnaire has been issued to initiate and track the review of contributed changes by the Eclipse Foundation's IP team the IPZilla bug number should be added as "CQ:" footer in the format shown below.

Example commit header for a functional change:

#############
Bug XXXXXX - Functional change in service XYZ

More detailed explanatory text (if necessary), describing the change, the direction of the fix etc.

Change-Id: I0000000000000000000000000000000000000000
Signed-off-by: Your Name <your.email@xxxxxxxxxxxx>
#############

Example commit for a non-functional functional change:

#############
Non functional white space change in service XYZ

<No detailed explanatory text is required for a trivial change>

Change-Id: I0000000000000000000000000000000000000000
Signed-off-by: Your Name <your.email@xxxxxxxxxxxx>
#############

Example commit header for a change which also required a Contribution Questionnaire:

#############
Bug XXXXXX - Huge functional contribution to service XYZ

More detailed explanatory text (mandatory for such a big change), describing the change, the direction of the fix etc.

CQ: XXXX
Change-Id: I0000000000000000000000000000000000000000
Signed-off-by: Your Name <your.email@xxxxxxxxxxxx>
#############

Thanks for contributing to the discussion!

--
Kind regards,
google.com/+AndreyLoskutov
_______________________________________________
platform-ui-dev mailing list
platform-ui-dev@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe from this list, visit
https://dev.eclipse.org/mailman/listinfo/platform-ui-dev

Back to the top