1Contributing to SCP-firmware
2============================
3
4Getting Started
5---------------
6
7- Make sure you have a [Gitlab account](https://gitlab.com/users/sign_in).
8- Clone the repo to your own machine.
9- Create a local topic branch based on the
10  [SCP-firmware](https://gitlab.arm.com/firmware/SCP-firmware) `main` branch.
11
12Making Changes
13--------------
14
15- Make commits of logical units. See these general
16  [Git guidelines](http://git-scm.com/book/ch5-2.html) for contributing to a
17  project.
18- Follow the project [coding style](./doc/code_style.md) and
19  [coding rules](./doc/code_rules.md).
20- Keep the commits on topic. If you need to fix another bug or make another
21  enhancement, please address it on a separate topic branch.
22- Avoid long commit series. If you do have a long series, consider whether
23  some commits should be squashed together or addressed in a separate topic.
24- Make sure your commit messages are in the proper format.
25- Where appropriate, please update the documentation.
26- Ensure that each changed file has the correct copyright and license
27  information.
28    - Files that entirely consist of contributions to this project should have a
29      copyright notice and BSD-3-Clause SPDX license identifier of the form as
30      shown in [license.md](./license.md)
31    - Files that contain changes to imported Third Party IP files should retain
32      their original copyright and license notices.
33- If you are submitting new files that you intend to be the technical
34  sub-maintainer for (for example, a new platform port), then also update the
35  [maintainers](./maintainers.md) file.
36- For topics with multiple commits, it is recommended that you make all the
37  documentation changes (and nothing else) in the last commit of the series.
38- Please test your changes. As a minimum, ensure you can do an AP boot.
39
40Submitting Changes
41------------------
42
43- Ensure forking the repository.
44  This requires the fork permission on the account, which can be obtained by
45  following: https://gitlab.arm.com/documentation/contributions.
46- Ensure that each commit in the series has at least one `Signed-off-by:` line,
47  using your real name and email address. The names in the `Signed-off-by:`
48  and `Author:` lines must match. If anyone else contributes to the commit,
49  they must also add their own `Signed-off-by:` line. By adding this line the
50  contributor certifies the contribution is made under the terms of the
51  [Developer Certificate of Origin (DCO)](./dco.txt).
52- Push your local changes to a new branch in your **fork**
53  (this might require setting up your SSH public key in your profile).
54  See [SSH](https://docs.gitlab.com/ee/user/ssh.html#add-an-ssh-key-to-your-gitlab-account)
55- Submit a [merge request](https://docs.gitlab.com/ee/user/ssh.html#add-an-ssh-key-to-your-gitlab-account)
56  from your **fork** to the [SCP-firmware](https://gitlab.arm.com/firmware/SCP-firmware)
57  _:warning: Please ensure you chose
58  [SCP-firmware](https://gitlab.arm.com/firmware/SCP-firmware) `main` as the target branch._
59    - The changes in the merge request (MR) will then undergo further review and
60      testing by the maintainers. Any review comments will be made as
61      comments on the MR.
62      This may require you to do some rework.
63    - When the changes are accepted, the maintainers will
64      integrate them.
65    - Typically, the maintainers will merge (fast-forward) the MR into the
66      `main` branch within the Gitlab UI by rebasing and then merging.
67    - Please avoid creating merge commits in the MR itself.
68    - If the MR is not based on a recent commit, the maintainers may rebase it
69      onto the `main` branch first, or ask you to do this.
70    - If the MR cannot be automatically merged, the maintainers will ask you
71      to rebase it onto the `main` branch.
72    - If after merging the maintainers find any issues, they may remove the
73      commits and ask you to create a new merge request to
74      resolve the problems.
75
76Followthrough
77-------------
78
79- From time to time new features may be added and older features/functionality
80may deprecated. Code owners would be required to modify their code to support
81such new requirements within a reasonable time. Failure to do so may result
82in the code being deprecated and no longer maintained as a part of the `main`
83branch.
84
85- Any regressions must be fixed as soon as possible. If you are unwilling or
86unable to fix the regression, (and nobody else does it for you), your commit
87might be removed.
88
89- The author of the commit is responsible for fixing any bugs in a timely
90manner.  Failure to address issues/bugs may result in the causal commit
91being removed.
92
93--------------
94*Copyright (c) 2018-2024, Arm Limited and Contributors. All rights reserved.*
95