Merge branch 'ag/contr' into 'kirkstone'

CONTRIBUTING.md: Regenerate using the CONTRIBUTING.sh script

See merge request !368

CONTRIBUTING.md

@@ -4,19 +4,29 @@ SPDX-FileCopyrightText: Huawei Inc.
 SPDX-License-Identifier: CC-BY-4.0
 -->
 
--   [Gitlab Contributions](#gitlab-contributions)
-    -   [Overview](#overview)
-    -   [Commit Guidelines](#commit-guidelines)
-    -   [Contributions to Documentation](#contributions-to-documentation)
--   [REUSE Compliance](#reuse-compliance)
-    -   [SPDX Information and REUSE Standard](#spdx-information-and-reuse-standard)
-        -   [SPDX Header Example](#spdx-header-example)
-        -   [Substantial Contributions](#substantial-contributions)
--   [DCO sign-off](#dco-sign-off)
-    -   [Overview](#overview-1)
-    -   [Developer Certificate of Origin](#developer-certificate-of-origin)
--   [`oniro`-specific contributions process and guidelines](#oniro-specific-contributions-process-and-guidelines)
--   [Eclipse Contributor Agreement](#eclipse-contributor-agreement)
+- <a href="#eclipse-contributor-agreement" id="toc-eclipse-contributor-agreement">Eclipse Contributor Agreement</a>
+- <a href="#gitlab-contributions" id="toc-gitlab-contributions">Gitlab Contributions</a>
+  - <a href="#overview" id="toc-overview">Overview</a>
+  - <a href="#git-setup" id="toc-git-setup">Git setup</a>
+  - <a href="#commit-guidelines" id="toc-commit-guidelines">Commit Guidelines</a>
+  - <a href="#contributions-to-documentation" id="toc-contributions-to-documentation">Contributions to Documentation</a>
+    - <a href="#creating-merge-requests" id="toc-creating-merge-requests">Creating merge requests</a>
+- <a href="#reuse-compliance" id="toc-reuse-compliance">REUSE Compliance</a>
+  - <a href="#spdx-information-and-reuse-standard" id="toc-spdx-information-and-reuse-standard">SPDX Information and REUSE Standard</a>
+    - <a href="#spdx-header-example" id="toc-spdx-header-example">SPDX Header Example</a>
+    - <a href="#substantial-contributions" id="toc-substantial-contributions">Substantial Contributions</a>
+- <a href="#dco-sign-off" id="toc-dco-sign-off">DCO sign-off</a>
+  - <a href="#overview-1" id="toc-overview-1">Overview</a>
+  - <a href="#docs_dco" id="toc-docs_dco">Developer Certificate of Origin</a>
+- <a href="#oniro-specific-contributions-process-and-guidelines" id="toc-projectname-specific-contributions-process-and-guidelines"><code>oniro</code>-specific contributions process and guidelines</a>
+
+# Eclipse Contributor Agreement
+
+Before your contribution can be accepted by the project team, contributors must electronically sign the [Eclipse Contributor Agreement (ECA)](http://www.eclipse.org/legal/ECA.php).
+
+Commits must have a Signed-off-by field in the footer indicating that the author is aware of the terms by which the contribution has been provided to the project. Also, an associated Eclipse Foundation account needs to be in place with a signed Eclipse Contributor Agreement on file. These requirements are enforced by the Eclipse Foundation infrastructure tooling.
+
+For more information, please see the [Eclipse Committer Handbook](https://www.eclipse.org/projects/handbook/#resources-commit).
 
 # Gitlab Contributions
 
@@ -24,6 +34,19 @@ SPDX-License-Identifier: CC-BY-4.0
 
 Oniro Project handles contributions as [merge requests](https://docs.gitlab.com/ee/user/project/merge_requests/) to relevant repositories part of the Oniro Project [GitLab instance](https://gitlab.eclipse.org/eclipse/oniro-core). The flow for handling that is classic: fork-based merge requests. This means that once you have an account, you can fork any repository, create a branch 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).
 
+## Git setup
+
+Clone your fork locally, enter its directory and set:
+
+``` bash
+$ git config --local user.email <your_eclipse_account_email>
+$ git config --local user.name <your_eclipse_full_name>
+```
+
+To push and pull over HTTPS with Git using your account, you must set a password or [a Personal Access Token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) .
+
+If you want to push or pull repositories using SSH, you have to [add a SSH key](https://docs.gitlab.com/ee/user/ssh.html) to your profile.
+
 ## Commit Guidelines
 
 <div class="note">
@@ -42,39 +65,39 @@ At its core, contributing to the Oniro Project project means *wrapping* your wor
 
 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.
+- 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 `/contributing/dco` document.
-    -   All *trailer* lines are to be provided as part of the same text block - no empty lines in between the *trailers*.
+- 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 `/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>`.
+- 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:
 
@@ -97,23 +120,32 @@ In terms of file format, the project unifies its documentation as `ReStructuredT
 
 As a rule of thumb, anything that ends up compiled in the project documentation is to maintain the RestructuredText file format. Text files that are not meant to be compiled as part of the project's documentation can be written in [Markdown](https://daringfireball.net/projects/markdown/). For example, a repository `README` file can be written in Markdown as it doesn't end up compiled in the project-wide documentation.
 
+### Creating merge requests
+
+Once your changes have been pushed to your fork, you are ready to prepare a merge request.
+
+1.  Go to your repository in an internet browser.
+2.  Create a merge request by clicking `Merge Requests` on left toolbar and press `New merge request`. Add an explainable description and create a merge request. Alternatively, you can enter the website of your fork. You should see a message that you pushed your branch to the repository. In the same section you can press `Create merge request`.
+3.  Before merging, it has to be reviewed and approved by Oniro Project repository maintainers. Read their review and add any required changes to your merge request.
+4.  After you polish your merge request, the maintainers will run the pipelines which check if your changes do not break the project and approve them. If everything is correct, your work is merged to the main project. Remember that each commit of the merge request should be a minimum, self-contained building block.
+
 # REUSE Compliance
 
 ## SPDX Information and REUSE Standard
 
 All projects and files for an hosted project **MUST** be [REUSE](https://reuse.software/) compliant. REUSE requires SPDX information for each file, rules for which are as follows:
 
--   Any new file must have a SPDX header (copyright and license).
--   For files that don't support headers (for example binaries, patches etc.) an associated `.license` file must be included with the relevant SPDX information.
--   Do not add Copyright Year as part of the SPDX header information.
--   The general rule of thumb for the license of a patch file is to use the license of the component for which the patch applies.
--   When modifying a file through this contribution process, you may (but don't have to) claim copyright by adding a copyright line.
--   Never alter copyright statements made by others, but only add your own.
+- Any new file must have a SPDX header (copyright and license).
+- For files that don't support headers (for example binaries, patches etc.) an associated `.license` file must be included with the relevant SPDX information.
+- Do not add Copyright Year as part of the SPDX header information.
+- The general rule of thumb for the license of a patch file is to use the license of the component for which the patch applies.
+- When modifying a file through this contribution process, you may (but don't have to) claim copyright by adding a copyright line.
+- Never alter copyright statements made by others, but only add your own.
 
 Some files will make an exception to the above rules as described below:
 
--   Files for which copyright is not claimed and for which this information was not trivial to fetch (for example backporting patches, importing build recipes etc. when upstream doesn't provide the SPDX information in the first place)
--   license files (for example `common-licenses` in bitbake layers)
+- Files for which copyright is not claimed and for which this information was not trivial to fetch (for example backporting patches, importing build recipes etc. when upstream doesn't provide the SPDX information in the first place)
+- license files (for example `common-licenses` in bitbake layers)
 
 ### SPDX Header Example
 
@@ -216,14 +248,3 @@ Signed-off-by: Joe Developer <joe.developer@example.com>
 
 Please note that by signing off the commit, you make a **legally binding
 statement** that you certify as in the [DCO sign-off](#dco-sign-off) section.
-
-# Eclipse Contributor Agreement
-
-Before your contribution can be accepted by the project team, contributors must electronically sign the
-[Eclipse Contributor Agreement (ECA)](http://www.eclipse.org/legal/ECA.php)
-
-Commits that are provided by non-committers must have a Signed-off-by field in the footer indicating that the author is aware of the terms by which the contribution has been provided to the project.
-The non-committer must additionally have an Eclipse Foundation account and must have a signed Eclipse Contributor Agreement (ECA) on file.
-
-For more information, please see the [Eclipse Committer Handbook](https://www.eclipse.org/projects/handbook/#resources-commit)
-