Re: [PATCH] Add CONTRIBUTING.md

[David Gibson <david@gibson.dropbear.id.au>]

[-- Attachment #1: Type: text/plain, Size: 4320 bytes --]

On Fri, Sep 12, 2025 at 03:54:23PM +0800, Yumei Huang wrote:
> Signed-off-by: Yumei Huang <yuhuang@redhat.com>

Nice first draft, but I think it will need some further work before
being ready to merge.  Here are some things that are probably worth adding:


 * Incorporate the information in the "Contribute" section
   of README.md (and change README to reference this document)
 * Code style conventions (kernel net-code)
 * The meaning of the "Signed-off-by" line (see kernel docs for full
   details or [0] or [1] for some simpler examples
 * Reference test/README.md for information on running the testsuite
   (that also needs updating)
 * Add a copyright and authorship banner (see README.md for an example)

A few more minor comments below.

[0]
https://gitlab.com/dgibson/exeter/-/blob/main/CONTRIBUTING.md?ref_type=heads#developers-certificate-of-origin
[1]
https://github.com/dgibson/dtc/blob/main/CONTRIBUTING.md#developers-certificate-of-origin

> ---
>  CONTRIBUTING.md | 86 +++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 86 insertions(+)
>  create mode 100644 CONTRIBUTING.md
> 
> diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
> new file mode 100644
> index 0000000..70e35b1
> --- /dev/null
> +++ b/CONTRIBUTING.md
> @@ -0,0 +1,86 @@
> +# 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.

By convention we wrap Markdown files at 80 columns, so it's easier to
read in text form.

> +
> +## Workflow
> +
> +### 1. Clone the project
> +
> +    git clone git://passt.top/passt
> +
> +### 2. Create a Branch
> +
> +    cd passt
> +    git checkout -b my-feature-branch
> +
> +Work on a separate branch instead of committing directly to `master`.
> +
> +### 3. Make Changes and Commit
> +
> +* Edit the source code or documentation.
> +
> +* Stage your changes:
> +
> +        git add <file1> <file2> ...
> +
> +* Commit with a clear message containing `Signed-off-by:` tag:
> +
> +        git commit -s    
> +
> +    Commit message format:
> +
> +        Subsystem: Brief summary (max ~50 chars)
> +
> +        More detailed explanation if needed, wrapped at 72 chars.
> +
> +        Signed-off-by: Your Name <author@email>
> +
> +    If there are some references, use "Links: " tag for simplicity.
> +
> +### 4. Generate Patches
> +
> +Use `git format-path` to generate patch(es):
> +
> +    git format-patch origin/master
> +
> +This will generate numbered patch files such as 0001-...patch, 0002-...patch, etc.
> +
> +If you send a series of patches, use the `--cover-letter` option with `git format-patch`:
> +
> +    git format-patch origin/main --cover-letter
> +
> +This will generate a cover letter besides your patches. You can edit the cover letter before sending.
> +
> +### 5. Send Patches
> +
> +Use `git send-email` to send patches directly to the mailing list:
> +
> +    git send-email --to=passt-dev@passt.top 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 000*.patch
> +

It might be worth mentioning git-publish
(https://github.com/stefanha/git-publish) as an easier way of doing
steps 4 & 5.

> +### 6. Responding to Review Feedback
> +
> +* Be open to feedback on both code and documentation.
> +
> +* Update your patch as needed, and regenerate patches:
> +
> +        git add <file1> <file2> ...
> +        git commit --amend
> +        git format-patch -v2 origin/master
> +
> +* Send the revised patches
> +
> +        git send-email --to=passt-dev@passt.top v2-000*.patch
> +
> +### 7. Tips and Best Practices
> +
> +* Keep changes focused and easy to review.
> +
> +* Test your changes thoroughly.
> +
> +* Include documentation updates if your change affects usage or APIs.
> +
> +Thank you for helping improve passt! Your contributions make a big difference.
> -- 
> 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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]