docs/6_How_To_Contribute/4_Submitting_Changes.md

   1 ---
   2 title: Submitting Changes
   3 ---
   4
   5 Carefully review the following before submitting a change. These guidelines
   6 apply to developers that are new to open source, as well as to experienced open
   7 source developers.
   8
   9 ## Change Requirements
  10
  11
  12 This section contains guidelines for submitting code changes for review. For
  13 more information on how to submit a change using Gerrit, please see [Working
  14 with Gerrit](./3_Working_with_Gerrit.md).
  15
  16 Changes are submitted as Git commits. Each commit must contain:
  17
  18 -  a short and descriptive subject line that is 72 characters or fewer, followed
  19    by a blank line.
  20 -  a change description with your logic or reasoning for the changes, followed
  21    by a blank line
  22 -  a Signed-off-by line, followed by a colon (Signed-off-by:)
  23 -  a Change-Id identifier line, followed by a colon (Change-Id:). Gerrit won't
  24    accept patches without this identifier.
  25
  26 A commit with the above details is considered well-formed. [This
  27 page](https://chris.beams.io/posts/git-commit/) is a very useful for the same.
  28
  29 All changes and topics sent to Gerrit must be well-formed. Informationally,
  30 ``commit messages`` must include:
  31
  32 -  **what** the change does,
  33 -  **why** you chose that approach, and
  34 -  **how** you know it works -- for example, which tests you ran.
  35
  36 For example: One commit fixes whitespace issues, another renames a function and
  37 a third one changes the code's functionality. An example commit file is
  38 illustrated below in detail:
  39
  40 ```sh
  41
  42 A short description of your change with no period at the end
  43
  44 You can add more details here in several paragraphs, but please keep each line
  45 width less than 80 characters. A bug fix should include the issue number.
  46
  47 Bug-AGL: [SPEC-<JIRA-ID>]
  48 Change-Id: IF7b6ac513b2eca5f2bab9728ebd8b7e504d3cebe1
  49 Signed-off-by: Your Name <commit-sender@email.address>
  50 ```
  51
  52 Include the issue ID in the one line description of your commit message for
  53 readability. Gerrit will link issue IDs automatically to the corresponding entry
  54 in Jira.
  55
  56 Each commit must also contain the following line at the bottom of the commit
  57 message:
  58
  59 ```sh
  60 Signed-off-by: Your Name <your@email.address>
  61 ```
  62
  63 The name in the Signed-off-by line and your email must match the change
  64 authorship information. Make sure your :file:``.git/config`` is set up
  65 correctly. Always submit the full set of changes via Gerrit.
  66
  67 When a change is included in the set to enable other changes, but it will not be
  68 part of the final set, please let the reviewers know this.