Discuss how to use GitHub properly and document the special kernel-headers process. Signed-off-by: Jason Gunthorpe <jgg@xxxxxxxxxx> --- Documentation/contributing.md | 164 ++++++++++++++++++++++++++++++++++ 1 file changed, 164 insertions(+) create mode 100644 Documentation/contributing.md diff --git a/Documentation/contributing.md b/Documentation/contributing.md new file mode 100644 index 00000000000000..e2868da3958138 --- /dev/null +++ b/Documentation/contributing.md @@ -0,0 +1,164 @@ +# 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. + +## 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@xxxxxxxxxxxxxxx. 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: + + $ 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: + + $ 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 alwaus 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@xxxxxxxxxxxxxxx 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@xxxxxxxxxxxxxxxxxxxxx> + +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. -- 2.31.1
