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 tool, 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 patches 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 tool, 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 patches 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.