Documentation/contributing.md - linux-rdma/rdma-core - Git at Google

 # 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.
	# 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.