Skip to end of metadata
Go to start of metadata


The detailed contribution process for different GENIVI projects is largely defined by each individual project maintainer. 

Here are the recommended rules unless otherwise overridden by a project maintainer.

They are required for GDP, and please refer to the full GDP Contribution Process.

Our rules are based on GNOME's commit message guidelines. A more extensive documentation including reasoning is available at http://coala.io/commit.

Those  are also more or less 100% compatible with the OpenEmbedded patch message guidelines and of course the Linux kernel guidelines, but those instructions also cover a lot of information regarding emailed patches, which is not our preferred process.  There might therefore be some duplication between these pages, but this is focused on exactly what we require for the GDP Contribution Process and is the default for all other GENIVI projects.

Example

 prefix: Short explanation of the commit
 
 Longer explanation explaining exactly what's changed and why, whether any
 external or private interfaces changed, what bugs were fixed (with bug
 tracker reference if applicable) and so forth. Be concise but not too brief.
 
 [GDP-227] Summary line of Jira ticket
 Signed-off-by: Joe Coder <joe@coder.org>

Details

  • The commit message is mainly for the other people, so they should be able to understand it now and six months later.  
  • Always add a brief description of the commit to the first line of the commit and terminate by two newlines (it will work without the second newline, but that is not nice for the interfaces).

  • First line (think of it as title or very short summary of change) must only be one sentence and should start with a capital letter unless it starts with a lowercase symbol or identifier. Don't use a trailing period either. It's recommended to not exceed 50 characters but it's not always possible/easy to follow this limit. In any case, don't exceed 74 characters. 
    Think about the most effective way to convey information.   You can use  "&" instead of "and".
  • Prefix the first line with one tag, to make it easier to know to which part of the module the commit applies. For example, a commit with "weston: Drop redundant files" in the meta-genivi-dev repository drops some files from weston recipes.  
  • The description part (the body) is normal prose and should use normal punctuation and capital letters where appropriate. Normally, for patches sent to a mailing list, the body is copied from there. This description part can be empty if the change is self-explanatory (eg: "Add DOAP file").  
  • Each line in description must not exceed 74 characters. (There is no limit on number of lines).
  • If this commit is related to a JIRA ticket, include a reference to a ticket, in it's own paragraph, in this format: "[GDP-227] Summary line of Jira ticket".
  • Commits must have a signature at the end of description part. E.g "Signed-off-by: Joe Coder <joe@coder.org>".    By signing you are attesting to the Developer Certificate of Origin.

  • Use imperative form of verbs rather than past tense when referring to changes introduced by commit in question. For example "Remove property X", not "Removed property X" and not "I removed...". 

Submodule updates

If a commit is changing the version of a submodule in a parent project, please use a script like this one for GDP.  It formats the summary correctly and provides a shortlog of the changes inside the submodule.  You can git commit --amend, to add a ticket-reference.  Usually a submodule bump should not need a lot of body text since change details are in the submodule history, but if the situation warrants an explanation, do it briefly, above the shortlog.  Prefer one submodule bump per commit, unless you know several submodules must be changed in sync to make the system compile, or to fix the referenced ticket, etc.

Submitter Checklist

It is very easy for developers (especially newcomers) to forget about the above points so its better to always go through this checklist for each patch before uploading it to bugzilla or pushing it to git.  

  • Summary line: 
    • Be sure to not exceed 72 characters. Try to not exceed 50. 
    • Use imperative/present tense. For example use "Add Hindi translation" instead of "Added Hindi translation". 
    • Summarize the change itself in the shortlog, not the bug or effects/benefits (that goes in description). 
    • Leave out the trailing period (full stop). 
    • You can use '&' instead of 'and' so the message gets shorter. 

    • Add a prefix in lower cases with a colon before the rest. 
    • Describe it for everyone, not just for you. 
    • Add a blank line after it. 
  • Description: 
    • Each line must not exceed 74 characters. 
    • You may leave out the description if the summary is self-explanatory. 
    • Use normal language and punctuation here. 
    • If the commit relates to a JIRA ticket, include reference to it. 
    • Add a Signed-off-by: line.  By doing so you are agreeing to the Developer Certificate of Origin
  • General: 
    • Give other users the credit they deserve. You would probably expect the same from others. (--author) 
    • If you use git revert command to undo a commit, git generates a default commit message specifying the hash and commit message of the commit you're undoing, but this is not enough to know *why* you're reverting it, so please add more comments to it.


The following information is primarily for GDP maintainers and committers:

Committer changes (fix-and-merge)

  • The person responsible to merge pull requests shall normally request the submitter to fix any issues with the patch / pull-request (PR) and resubmit
    This is good practice and teaches people to do it right next time.  Prefer to allow submitters to fix their own problems instead of putting such fixes into the commit message/history.
  • However, from time to time for efficiency's sake the committer might choose to fix a minor nitpick during the merge.
  • As a principle, anyone touching the patch must sign it.  To track what changes were done by the submitter, vs. the committer, the committer shall comment and sign their change.  This includes any change (i.e. addition) to the description.  All of the standard rules still apply, and even more strictly so.  For example the committer must obviously not add unrelated changes into the same commit.  In that case, make a new commit.
  • NOTE: Rebasing a PR to bring it up to date with the target branch can be done at any time.  It's also possible to split, squash or add a new commit among the ones provided by the PR.  Normally such major changes should be deferred to the submitter, but if the submitter has limited git experience then the committer/maintainer doing it might be preferable.
  • Only rebasing does not change any commits.  No change in comments and no new Sign-off shall be added. 
  • Always note a comment in the PR when pushing changes to the PR.  Make sure to read GDP Contribution Process, chapter Rebasing and updating PRs for details.
  • NOTE: Amended patches shall also always be force-pushed to the source branch of the pull request.  This is to ensure that GitHub will recognize the PR as merged despite that the patch has changed.
  • Use fix-and-merge sparingly for nitpicks.

Example of fix-and-merge (amended patch):

 prefix: Short explanation of the commit
 
 Longer explanation explaining exactly what's changed (first) and why (second), 
whether any  external or private interfaces changed, what bugs were fixed (with
bug  tracker reference if applicable) and so forth. Be concise but not too brief.    [GDP-227] Summary line of Jira ticket
 Signed-off-by: Joe Coder <joe@coder.org>

Fixed a white-space issue.
Noting that this patch also changes foo to bar (omitted above).

Signed-off-by: Committer Name <email@email.foo>


  • No labels