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
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
|
# Contributing to rdma-core
rdma-core is a userspace project for a Linux kernel interface and follows many
of the same expectations as contributing to the Linux kernel:
- One change per patch
Carefully describe your change in the commit message and break up work into
appropriate reviewable commits.
Refer to [Linux Kernel Submitting Patches](https://github.com/torvalds/linux/blob/master/Documentation/process/submitting-patches.rst)
for general information.
- Developer Certificate of Origin 'Signed-off-by' lines
Include a Signed-off-by line to indicate your submission is suitable
licensed and you have the legal authority to make this submission
and accept the [DCO](#developers-certificate-of-origin-11)
- Broadly follow the [Linux Kernel coding style](https://github.com/torvalds/linux/blob/master/Documentation/process/coding-style.rst)
As in the Linux Kernel, commits that are fixing bugs should be marked with a
Fixes: line to help backporting.
Test your change locally before submitting it, you can use 'buildlib/cbuild'
to run the CI process locally and ensure your code meets the mechanical
expectations before sending the PR.
# Using GitHub
Changes to rdma-core should be delivered via [GitHub Pull Request](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests)
to the [rdma-core](https://github.com/linux-rdma/rdma-core) project.
Each pull request should have a descriptive title and "cover letter" summary
indicating what commits are present.
A brief summary of the required steps:
- Create a github account for yourself
- [Clone](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository-from-github/cloning-a-repository)
the [rdma-core](https://github.com/linux-rdma/rdma-core) project in GitHub
- Setup a local clone of your repository using 'git clone'.
- Ensure your local branch is updated to the tip of rdma-core
- Make your change. Form the commits and ensure they are correct
- Push to your local git repository to your GitHub on a dedicated branch.
- Using the GitHub GUI make a Pull Request from the dedicated branch to
rdma-core
## Making Revisions
If changes are required they should be integrated into the commits and the
pull request updated via force push to your branch. As a policy rdma-core
wishes to have clean commit objects. As a courtesy to others describe the
changes you made in a Pull Request comment and consider to include a
before/after diff in that note.
Do not close/open additional pull requests for the same topic.
## Continuous Integration
rdma-core performs a matrix of compile tests on each Pull Request. This is to
ensure the project continues to be buildable on the wide range of supported
distributions and compilers. These tests include some "static analysis" passes
that are designed to weed out bugs.
Serious errors will result in a red X in the PR and will need to be corrected.
Less serious errors, including checkpatch related, will show up with a green
check but it is necessary to check the details to see that everything is
appropriate. checkpatch is an informative too, not all of its feedback is
appropriate to fix.
A build similar to AZP can be run locally using docker and the
'buildlib/cbuild' script.
```sh
$ buildlib/cbuild build-images azp
$ buildlib/cbuild pkg azp
```
## Coordinating with Kernel Changes
Some changes consume a new uAPI that needs to be added to the kernel. Adding a
new rdma uAPI requires kernel and user changes that must be presented together
for review.
- Prepare the kernel patches and rdma-core patches together. Test everything
- Send the rdma-core patches as a PR to GitHub and possibly the mailing list
- Send the kernel pathces to linux-rdma@vger.kernel.org. Refer to the matching
GitHub PR in the cover letter by URL
- The GitHub PR will be marked with a 'needs-kernel-patch' tag and will not
advance until the kernel component is merged.
Keeping the kernel include/uapi header files in sync requires some special
actions. The first commit in the series should synchronize the kernel headers
copies in rdma-core with the proposed new kernel-headers that this change
requires. This commit is created with the script:
```sh
$ kernel-headers/update ~/linux.git HEAD --not-final
```
It will generate a new commit in the rdma-core.git that properly copies the
kernel headers from a kernel git tree. The --not-final should be used until
official, final, commits are available in the canonical [git
tree](http://git.kernel.org/pub/scm/linux/kernel/git/rdma/rdma.git)
This will allow the CI to run and the patches to be reviewed.
Once the kernel commits are applied a final git rebase should be used to
revise the kernel-headers commit:
```sh
$ kernel-headers/update ~/linux.git <commit ID> --amend
```
The updated commits should be force pushed to GitHub.
Newer kernels should always work with older rdma-core and newer rdma-core
should always work with older kernels. Changes forcing the simultaneous
upgrade of the kernel and rdma-core are forbidden.
# Participating in the Mailing List
Patches of general interest should be sent to the mailing list
linux-rdma@vger.kernel.org for detailed discussion. In particular patches that
modify any of the ELF versioned symbols or external programming API should be
sent to the mailing list.
While all patches must have a GitHub Pull Request created, minor patches can
skip the mailing list process.
# Making a new library API
All new library APIs that can be called externally from rdma-core require a
man page describe the API and must be sent to the mailing list for review.
This includes device specific "dv" APIs.
Breaking the ABI of any exported symbol is forbidden.
# Developer's Certificate of Origin 1.1
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; or
(b) The contribution is based upon previous work that, to the best
of my knowledge, is covered under an appropriate open source
license and I have the right under that license to submit that
work with modifications, whether created in whole or in part
by me, under the same open source license (unless I am
permitted to submit under a different license), as indicated
in the file; or
(c) The contribution was provided directly to me by some other
person who certified (a), (b) or (c) and I have not modified
it.
(d) I understand and agree that this project and the contribution
are public and that a record of the contribution (including all
personal information I submit with it, including my sign-off) is
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.
then you just add a line saying:
Signed-off-by: Random J Developer <random@developer.example.org>
using your real name (sorry, no pseudonyms or anonymous contributions.)
This will be done for you automatically if you use ``git commit -s``.
Reverts should also include "Signed-off-by". ``git revert -s`` does that
for you.
|
