diff --git a/documentation/contributing.rst b/documentation/contributing.rst index 7a31dfb4d0d2b446d2f4714ac531b5f5aa8813a2..c2057cf17e8a8d24b89e10a72c19caf2a100e50c 100644 --- a/documentation/contributing.rst +++ b/documentation/contributing.rst @@ -92,7 +92,7 @@ it is copied below. Commit guidelines ***************** -Commits and patches added should follow the `OpenEmbedded patch guidelines `_. +Commits and patches added should follow the `OpenEmbedded patch guidelines `_ with the following additions. The component being changed in the shortlog should be prefixed with the layer name (without meta-), for example: @@ -103,6 +103,194 @@ layer name (without meta-), for example: cassini-doc: Added foobar v2 documentation +========================== +Commit messages guidelines +========================== + +Commit messages should follow the guidelines below, for reasons explained by Chris Beams in `How to Write a Git Commit Message `_: + +- The commit subject and body must be separated by a blank line. +- The commit subject must start with a capital letter. +- The commit subject must not be longer than 72 characters. +- The commit subject must not end with a period. +- The commit body must not contain more than 72 characters per line. +- Commits that change 30 or more lines across at least 3 files should + describe these changes in the commit body. +- Use issues and merge requests' full URLs instead of short references, + as they are displayed as plain text outside of GitLab. +- The merge request should not contain more than 10 commit messages. +- The commit subject should contain at least 3 words. + +**Important notes:** + +- If the guidelines are not met, the MR may not pass the `Danger checks `_. +- Consider enabling `Squash and merge `_ + if your merge request includes "Applied suggestion to X files" commits, so that Danger can ignore those. +- The prefixes in the form of *[prefix]* and *prefix:* are allowed (they can be all lowercase, as long + as the message itself is capitalized). For instance, *danger: Improve Danger behavior* and + *[API] Improve the labels endpoint* are valid commit messages. + +-------------------------- +Why these standards matter +-------------------------- + +1. Consistent commit messages that follow these guidelines make the history more readable. +#. Concise standard commit messages helps to identify breaking changes for a deployment or ~"master:broken" quicker when + reviewing commits between two points in time. + +----------------------- +Commit message template +----------------------- + +Example commit message template that can be used on your machine that embodies the above (guide for `how to apply template `_):: + + # (If applied, this commit will...) (Max 72 characters) + # |<---- Using a Maximum Of 72 Characters ---->| + + + # Explain why this change is being made + # |<---- Try To Limit Each Line to a Maximum Of 72 Characters ---->| + + # Provide links or keys to any relevant tickets, articles or other resources + # Use issues and merge requests' full URLs instead of short references, + # as they are displayed as plain text outside of GitLab + + # --- COMMIT END --- + # -------------------- + # Remember to + # Capitalize the subject line + # Use the imperative mood in the subject line + # Do not end the subject line with a period + # Subject must contain at least 3 words + # Separate subject from body with a blank line + # Commits that change 30 or more lines across at least 3 files should + # describe these changes in the commit body + # Use the body to explain what and why vs. how + # Can use multiple lines with "-" for bullet points in body + # For more information: https://cbea.ms/git-commit/ + # -------------------- + + +***************** +Changelog entries +***************** +This section contains instructions for when and how to generate a changelog entry +file, as well as information and history about our changelog process. + +======== +Overview +======== +Each bullet point, or **entry**, in our `CHANGELOG.md `_ file is generated from the subject line of a Git commit. Commits are included +when they contain the Changelog `Git trailer `_. When generating the changelog, author and merge request details are added +automatically. + +The Changelog trailer accepts the following values: + +- feature: New feature added/enabled +- bug: Bug fix +- deprecated: New deprecation +- removed: Feature removal +- security: Security fix +- performance: Performance improvement +- other: Other + +An example of a Git commit to include in the changelog is the following:: + + Update git vendor to gitlab + + Now that we are using gitaly to compile git, the git version isn't known + from the manifest, instead we are getting the gitaly version. Update our + vendor field to be `gitlab` to avoid cve matching old versions. + + Changelog: changed + MR: https://gitlab.com/foo/bar/-/merge_requests/123 + + +--------------------------------------- +Overriding the associated merge request +--------------------------------------- + +GitLab automatically links the merge request to the commit when generating the changelog. If you want to override the merge request to link to, you can specify +an alternative merge request using the MR trailer:: + + Update git vendor to gitlab + + Now that we are using gitaly to compile git, the git version isn't known + from the manifest, instead we are getting the gitaly version. Update our + vendor field to be `gitlab` to avoid cve matching old versions. + + Changelog: changed + MR: https://gitlab.com/foo/bar/-/merge_requests/123 + +The value must be the full URL of the merge request. + +================================ +What warrants a changelog entry? +================================ + +- Security fixes **must** have a changelog entry, with ``Changelog`` trailer set to ``security``. +- Any user-facing change **must** have a changelog entry. Example: "meta-cassini now supports AWS Greengrass as a cloud option" +- A fix for a regression introduced and then fixed in the same release (such as fixing a bug introduced during a release candidate) **should not** have a changelog entry. +- Any developer-facing change (such as refactoring, technical debt remediation, or test suite changes) **should not** have a changelog entry. +- Any contribution from a community member, no matter how small, **may** have a changelog entry regardless of these guidelines if the contributor wants one. +- Any experimental changes **should not** have a changelog entry. +- An MR that includes only documentation changes **should not** have a changelog entry. + +============================== +Writing good changelog entries +============================== + +A good changelog entry should be descriptive and concise. It should explain the change to a reader who has *zero context* about the change. If you have trouble making it both concise and descriptive, err on the side of descriptive. + +- **Bad:** Use newest version. +- **Good:** Updated to latest U-Boot version to get FF-A support. + +The first example provides no context of where the change was made, or why, or how it benefits the user. + +- **Bad:** Update syntax. +- **Good:** Update bitbake files to new append syntax to allow use with > hardknott yocto versions. + +Again, the first example is too vague and provides no context. + +- **Bad:** Fixes and Improves , usage in config files. +- **Good:** Fix parsec config file so that parsec can encrypt large payloads from clients. + +The first example is too focused on implementation details. The user doesn't care that we changed comma's they care about the *end result* of those changes. + +- **Bad:** Extended parsec input buffer for encrypt operations +- **Good:** Allow parsec to encrypt message upto 512Kb in size when using incremental encryption API's + +The first example focuses on *how* we fixed something, not on *what* it fixes. The rewritten version clearly describes the *end benefit* to the user (larger possible data sets), and *when* (calling the incremental encryption API's). + +Use your best judgement and try to put yourself in the mindset of someone reading the compiled changelog. Does this entry add value? Does it offer context about *where* and *why* the change was made? + +================================= +How to generate a changelog entry +================================= + +Git trailers are added when committing your changes. This can be done using your text editor of choice. Adding the trailer to an existing commit requires either amending to the commit (if it's the most recent one), or an interactive rebase using ``git rebase -i``. + +To update the last commit, run the following:: + + git commit --amend + +You can then add the Changelog trailer to the commit message. If you had already pushed prior commits to your remote branch, you have to force push the new commit:: + + git push -f origin your-branch-name + +To edit older (or multiple commits), use ``git rebase -i HEAD~N`` where ``N`` is the last N number of commits to rebase. Let's say you have 3 commits on your branch: A, B, and C. If you want to update commit B, you need to run:: + + git rebase -i HEAD~2 + +This starts an interactive rebase session for the last two commits. When started, Git presents you with a text editor with contents along the lines of the following:: + + pick B Subject of commit B + pick C Subject of commit C + +To update commit B, change the word pick to reword, then save and quit the editor. Once closed, Git presents you with a new text editor instance to edit the commit message of commit B. Add the trailer, then save and quit the editor. If all went well, commit B is now updated. + +For more information about interactive rebases, take a look at the `Git documentation `_. + ****************** Submitting changes ******************