Newer
Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
## Contributing
## License details
Please use an [SPDX license identifier](http://spdx.org/licenses/) in every source file following the [recommendations](https://spdx.dev/spdx-specification-21-web-version/#h.twlc0ztnng3b) to make it easier for users to understand and review licenses.
The full original [Apache 2.0 license text](http://www.apache.org/licenses/LICENSE-2.0) is in [LICENSE-apache-2.0.txt](LICENSE-apache-2.0.txt). Each source file should start with your copyright line followed by the SPDX identifier as shown here:
```
Copyright (c) [First year]-[Last year], **Your Name or Company Here**
SPDX-License-Identifier: Apache-2.0
```
For example, for a .c/.h file:
```
/* Copyright (c) 2013-2021, Arm Limited and Contributors. All rights reserved.
* SPDX-License-Identifier: Apache-2.0
*/
```
## Code Style checks
Source code in this repository is formatted with [Clang-Format Styling](https://clang.llvm.org/docs/ClangFormatStyleOptions.html). Style format config we use is [available here](./.clang-format). We use `clang-format` version 13.
Every contribution to this repository is checked for Clang-Format styling in our Continuous Integration (CI). It is a very good practice to run clang-format style checks locally in your development environment before creating a Merge Request to this repository to save time.
Depending on the development environment, installation instructions for clang-format would vary. Please refer to [official documentation](https://llvm.org/) for installation instructions.
Once, you have `clang-format` installed, you can run style code by executing as given below
Please note that we use clang-format-13, make sure that you have installed the same version.
```
# To format a single file
clang-format -i <path_to_file>
# To batch format files
git ls-files '*.h' '*.c' '*.cpp' | xargs clang-format -i
```
💡 If you have Docker installed, you can run the clang-format styling as given below. This makes use of same docker image used in our CI.
```
cd path/to/source/code/checkout/from/this/repository
docker run --rm -v $PWD:/app -w /app mcudriverhal/ci-build-env:clang-format-13 /bin/bash -c "git ls-files '*.h' '*.c' '*.cpp'| xargs clang-format -i"
```
## Developer’s Certificate of Origin
Each commit must have at least one `Signed-off-by:` line from the committer to certify that the contribution is made under the terms of the [Developer Certificate of Origin](./DCO.txt).
If you set your `user.name` and `user.email` as part of your git configuration, you can add a signoff to your commit automatically with `git commit -s`. You have to use your real name (i.e., pseudonyms or anonymous contributions cannot be made). This is because the DCO is a legally binding document.
## Commit guidelines
For git commit messages, we follow Chris Beams' [7 rules](https://chris.beams.io/posts/git-commit/#seven-rules) with the following exceptions:
- Commit message subject is allowed to be 72 characters wide.
- Subject line must include a prefix that identifies the subsystem being changed. For example:
```
hal/source: Remove unused definitions from mbed_compat.c
```
If file belongs to no subsystem, i.e. files at the root of the repo, then use the file name as prefix.
- Each commit must have a Message Body which concisely describes what is being changed, how and why.
- Each commit must contain a `Signed-off-by` line.
In addition:
- When fixing bugs caused by an older commit (not at the HEAD), please mention the issue's origin by providing the merge request number or commit SHA of the original change in the commit message.
- Each commit should build cleanly when applied on top of one another. This ensures that `git bisect` is not broken. In addition, each commit should pass all CI tests.
- Each commit should address a single identifiable issue and every attempt should be made to ensure that unrelated changes don't seep in.
- In general, commit diffs should be small and self contained unless new functionality is being added.
## Pull request guidelines
- Please create separate pull requests for each topic; each pull request needs a clear unity of purpose. In particular, separate code formatting and style changes from functional changes. This makes each pull request’s true contribution clearer, so review is quicker and easier.
- Update any documentation related to your code changes and make it part of the pull request.
- Whenever you make changes to a file, please make sure to update the copyright year in the license header to the current gregorian calendar year.
- Ensure that all changes conform to the [Coding Style](#Code-Style-checks) and all commit messages conform to [Commit guidelines](#Commit-guidelines) before opening a pull request.
- Once the pull request is opened and review is requested from reviewers, please refrain from adding changes until an initial pass is completed by one of the reviewers. If you wish to make changes, please mark your PR as "do not merge" and only remove this label when its ready for review.
- Every new addition to an already opened pull request should be commented to inform the reviewers on what has changed.
- Keep a linear git history: no merge commits are allowed, always rebase your branch.
- Preserve the history until the review is completed. Use `git commit --fixup` to add fixes. Once review is completed, run `git rebase --autosquash` to clean the history.
## Pull request process
PRs should go through the following steps:
1. "needs: review". Maintainers and Codeowners will review. They can add comments, make request for changes or ask to rebase. Initial approval is required to indicate readiness to progress.
1. "needs: work" (optional). The author of the PR needs to update it as per comments or simple rebase. This step can be skipped if a PR does not require changes nor rebase.
1. "needs: final review". Once the PR was initially reviewed and rebased, a final review is needed before approval. **Note**: authors of PRs should not rebase or do a force-push while in this step.
1. "do not merge" (optional). A PR is useful for discussions, prototyping or demo, but it's not intended to be merged (soon).
## Codeowners
Technical ownership of the codebase falls on the codeowners and all contributions are ultimately merged by the them. The members are listed in the [CODEOWNERS](CODEOWNERS) file.
## Maintainers
Maintainers provide guidence and direction to contributors.
Martin Kojtal
:email: `Martin Kojtal <Martin.Kojtal@arm.com>`
:gitlab: `https://gitlab.arm.com/Martin.Kojtal`
Anna Bridge
:email: `Anna Bridge <Anna.Bridge@arm.com>`
:gitlab: `https://gitlab.arm.com/Anna.Bridge`