diff --git a/contributing/gitlab.rst b/contributing/gitlab.rst index 290f4cc3f7eabc4c5d9e4ac760bb7fd4c388bbd3..8b9bc1ea0e08faf9a7bf76b6493be7de7edd503a 100644 --- a/contributing/gitlab.rst +++ b/contributing/gitlab.rst @@ -21,6 +21,109 @@ with proposed changes and raise a merge request against the forked repository. More generic information you can find on the Gitlab's documentation as part of `"Merge requests workflow" <https://docs.gitlab.com/ee/development/contributing/merge_request_workflow.html>`_. +Commit Guidelines +***************** + +.. note:: + + If you are new to ``git``, start by reading the official + `Getting Started Document <https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup>`_. + +At its core, contributing to OpenHarmony means *wrapping* your work as ``git`` +commits. How we handle this has an impact on rebasing, cherry-picking, +back-porting, and ultimately exposing consistent documentation through its +logs. + +To achieve this, we maintain the following commit guidelines: + +* Each commit should be able to stand by itself providing a building block as + part of the MR. + + * A good balance of granularity with scoped commits helps to handle backports + (e.g. cherry-picks) and also improves the ability to review smaller chunks + of code taking commit by commit. + +* Changes that were added on top of changes introduced in the MR, should be + squashed into the initial commit. + + * For example, a MR that introduced a new build system recipe and, as a + separate commit, fixed a build error in the initial recipe. The latter + commit should be squashed into the initial commit. + * For example, a MR introducing a new docs chapter and also adding, as a + separate commit, some typo fixes. The latter commits should be squashed into + the initial commit. + * There is a small set of exceptions to this rule. All these exceptions + gravitate around the case where an MR, even if it provides multiple commits + in the same scope (for example, to the same build recipe), each of the + commits has a very specific purpose. + + * For example, a line formating change followed by a chapter addition + change in the same documentation file. + * Also, it can be the case of two functional changes that are building + blocks in the same scope. + * Another example where commits are not to be squashed is when having a + commit moving the code and a commit modifying the code in the new + location. + +* Make sure you clean your code of trailing white spaces/tabs and that each + file ends with a new line. + +* Avoid *merge* commits as part of your MR. Your commits should be rebased on + top of the *HEAD* of the destination branch. + +As mentioned above, *git log* becomes informally part of the documentation of +the product. Maintaining consistency in its format and content improves +debugging, auditing, and general code browsing. To achieve this, we also require +the following commit message guidelines: + +* The *subject* line (the first line) needs to have the following format: + ``scope: Title limited to 80 characters``. + + * Use the imperative mood in the *subject* line for the *title*. + * The *scope* prefix (including the colon and the following whitespace) is + optional but most of the time highly recommended. For example, fixing an + issue for a specific build recipe, would use the recipe name as the + *scope*. + * The *title* (the part after the *scope*) starts with a capital letter. + * The entire *subject* line shouldn't exceed 80 characters (same text + wrapping rule for the commit body). + +* The commit *body* separated by an empty line from the *subject* line. + + * The commit *body* is optional but highly recommended. Provide a clear, + descriptive text block that accounts for all the changes introduced by a + specific commit. + * The commit *body* must not contain more than 80 characters per line. + +* The commit message will have the commit message *trailers* separated by a new + line from the *body*. + + * Each commit requires at least a *Signed-off-by* trailer line. See more as + part of the :doc:`/contributing/dco` document. + * All *trailer* lines are to be provided as part of the same text block - no + empty lines in between the *trailers*. + +Additional commit message notes: + +* Avoid using special characters anywhere in the commit message. +* Be succinct but descriptive. +* Have at least one *trailer* as part of each commit: *Signed-off-by*. +* You can automatically let ``git`` add the *Signed-off-by* by taking advantage + of its ``-s`` argument. +* Whenever in doubt, check the existing log on the file (``<FILE>``) you are + about to commit changes, using something similar to: ``git log <FILE>``. + +Example of a full git message: + +.. code-block:: text + + busybox: Add missing dependency on virtual/crypt + + Since version 1.29.2, the busybox package requires virtual/crypt. Add this + to DEPENDS to make sure the build dependency is satisfied. + + Signed-off-by: Joe Developer <joe.developer@example.com> + Contributions to Documentation ******************************