On Thu, Sep 18, 2025 at 09:17:34AM +0800, Yumei Huang wrote: > Signed-off-by: Yumei Huang Reviewed-by: David Gibson I'm sure there's more stuff that could be included or clarified, but this is a big improvement over what we have now, and we can keep revising it in future. > --- > CONTRIBUTING.md | 152 ++++++++++++++++++++++++++++++++++++++++++++++++ > README.md | 4 +- > 2 files changed, 155 insertions(+), 1 deletion(-) > create mode 100644 CONTRIBUTING.md > > diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md > new file mode 100644 > index 0000000..5f41bc3 > --- /dev/null > +++ b/CONTRIBUTING.md > @@ -0,0 +1,152 @@ > + > + > +# Contributing to passt > + > +Thank you for your interest in contributing! This document explains how > +to prepare patches and participate in the email-based review process. > + > +## Workflow > + > +### 1. Clone the project > + > + git clone git://passt.top/passt > + > +### 2. Make Changes and Commit > + > +* You can decide to work on the master branch or a separate branch as below: > + > + cd passt > + git checkout -b my-feature-branch > + > +* Edit the source code or documentation following the > + [Linux kernel coding style](https://www.kernel.org/doc/html/latest/process/coding-style.html). > + > +* Stage your changes: > + > + git add ... > + > +* Commit with a message: > + > + git commit > + > + The message should describe your changes. See > + [this link](https://docs.kernel.org/process/submitting-patches.html#describe-your-changes) > + for details. Here is an example of commit message format: > + > + Subsystem: Brief summary > + > + More detailed explanation if needed, wrapped at 72 chars. > + > + The `Subsystem` means: which part of the code your change touches. > + For example, it could be "tcp", "test", or "doc" etc. > + > + If there are some references, use "Links:" tag for anything. > + > + Besides, passt uses the Linux kernel's "Signed-off-by" process. If you can > + certify the below: > + > + 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. > + > + Add this line: > + > + Signed-off-by: Random J Developer > + > + using your name. 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. > + > + Any further SoBs (Signed-off-by:'s) following the author's SoB are > + from people handling and transporting the patch, but were not involved > + in its development. SoB chains should reflect the **real** route a > + patch took as it was propagated to the maintainers, with the first SoB > + entry signalling primary authorship of a single author. > + > +### 3. Generate Patches > + > +Use `git format-patch` to generate patch(es): > + > + git format-patch -o outgoing/ origin/master > + > +It will generate numbered patch files such as 0001-...patch, 0002-...patch > +etc. in the `outgoing` folder. > + > +Or you can use `git format-patch -n`. For example if you want to format just > +three patches: > + > + git format-patch -3 -o outgoing/ > + > +If you send a series of patches, use the `--cover-letter` option with > +`git format-patch`: > + > + git format-patch -o outgoing/ origin/main --cover-letter > + > +This will generate a cover letter besides your patches. Edit the cover > +letter before sending. > + > +### 4. Send Patches > + > +Use `git send-email` to send patches directly to the mailing list: > + > + git send-email --to=passt-dev@passt.top 000*.patch -o outgoing/000*.patch > + > +If there are CCs (e.g. maintainers, reviewers), you can add them with `--cc`: > + > + git send-email --to=passt-dev@passt.top --cc=maintainer@example.com > + outgoing/000*.patch > + > +### 5. Responding to Review Feedback > + > +* Be open to feedback on both code and documentation. > + > +* Update your patch as needed, and regenerate patches: > + > + git add ... > + git commit --amend > + git format-patch -v2 -o outgoing/ origin/master > + > +* Send the revised patches: > + > + git send-email --to=passt-dev@passt.top outgoing/v2-000*.patch > + > +### 6. Tips and Best Practices > + > +* Keep changes focused and easy to review. Please refer to > + [split-changes](https://docs.kernel.org/process/submitting-patches.html#split-changes) > + to separate each logical change into a separate patch. > + > +* Test your changes thoroughly. Refer to > + [test/README.md](/passt/tree/test/README.md) file for testing. > + It's recommended to run at least a 'make cppcheck' and 'make clang-tidy' > + other than a specific manual test of the functionality / issue at hand. > + > +* Include documentation updates if your change affects usage. > + > +Thank you for helping improve passt! Your contributions make a big difference. > diff --git a/README.md b/README.md > index 8f188f4..897ae8b 100644 > --- a/README.md > +++ b/README.md > @@ -625,7 +625,9 @@ See also the [test logs](/builds/latest/test/). > > ### [Mailing Lists](/passt/lists) > * Submit, review patches, and discuss development ideas on > - [`passt-dev`](https://lists.passt.top/postorius/lists/passt-dev.passt.top/) > + [`passt-dev`](https://lists.passt.top/postorius/lists/passt-dev.passt.top/). > + Please refer to the [CONTRIBUTING.md](/passt/tree/CONTRIBUTING.md) file for > + details. > > * Ask your questions and discuss usage needs on > [`passt-user`](https://lists.passt.top/postorius/lists/passt-user.passt.top/) > -- > 2.47.0 > -- David Gibson (he or they) | I'll have my music baroque, and my code david AT gibson.dropbear.id.au | minimalist, thank you, not the other way | around. http://www.ozlabs.org/~dgibson