From mboxrd@z Thu Jan 1 00:00:00 1970 Authentication-Results: passt.top; dmarc=pass (p=quarantine dis=none) header.from=redhat.com Authentication-Results: passt.top; dkim=pass (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=dEHcGvay; dkim-atps=neutral Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by passt.top (Postfix) with ESMTPS id 373DE5A068E for ; Wed, 17 Sep 2025 05:51:34 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1758081093; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=19NxX1TCoyPya6FwfvlLssfq4l4g31LUEC/aWW/pnO0=; b=dEHcGvay6FGEkHz1qkMmyFYHYQ+LoOhnLdnEKpu1+Fq8WWcUyHVCRuXnD0C+FUlqA8EEet zFZeFoJ368xOhdil/6Ml6ECzih1HCDSt5Vd1f0fEY9qF0ARKpMeIQsPXSzD9cmCfx6Ryfq sfYw7eO5odUPbE26lANI720Z5Acdahs= Received: from mx-prod-mc-02.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-346-fQugcSLtNum7CtplBoKPsw-1; Tue, 16 Sep 2025 23:51:29 -0400 X-MC-Unique: fQugcSLtNum7CtplBoKPsw-1 X-Mimecast-MFC-AGG-ID: fQugcSLtNum7CtplBoKPsw_1758081088 Received: from mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.17]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 510061956087; Wed, 17 Sep 2025 03:51:27 +0000 (UTC) Received: from fedora.redhat.com (unknown [10.72.112.74]) by mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 06B7C195608E; Wed, 17 Sep 2025 03:51:23 +0000 (UTC) From: Yumei Huang To: passt-dev@passt.top, sbrivio@redhat.com Subject: [PATCH v2] Add CONTRIBUTING.md Date: Wed, 17 Sep 2025 11:51:20 +0800 Message-ID: <20250917035120.11728-1-yuhuang@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.0 on 10.30.177.17 X-Mimecast-Spam-Score: 0 X-Mimecast-MFC-PROC-ID: a1zQfTsFed2BXbTGdpL31dqWwDSU9Q2053Oj3qxsuRw_1758081088 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: 8bit content-type: text/plain; charset="US-ASCII"; x-default=true Message-ID-Hash: 66JH2SULFU4LKX65GJLFYYGF5CCCARSS X-Message-ID-Hash: 66JH2SULFU4LKX65GJLFYYGF5CCCARSS X-MailFrom: yuhuang@redhat.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; emergency; loop; banned-address; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header CC: david@gibson.dropbear.id.au, yuhuang@redhat.com X-Mailman-Version: 3.3.8 Precedence: list List-Id: Development discussion and patches for passt Archived-At: Archived-At: List-Archive: List-Archive: List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: Signed-off-by: Yumei Huang --- CONTRIBUTING.md | 152 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 6 +- 2 files changed, 156 insertions(+), 2 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..13fba69 --- /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 + + +### 3. 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", and "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 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. + + 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. + +### 4. Generate Patches + +Use `git format-path` 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 exmaple 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. 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 -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 + +### 6. 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 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. Please refer to [split-changes](https://docs.kernel.org/process/submitting-patches.html#split-changes) + to seperate each logical change into a separate patch. + +* Test your changes thoroughly. Refer to [test/README.md](/passt/tree/test/README.md) + 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..6ba6441 100644 --- a/README.md +++ b/README.md @@ -553,7 +553,7 @@ See also the [test logs](/builds/latest/test/). man ./passt.1 * run the demo script, that detaches user and network namespaces, configures the - new network namespace using `pasta`, starts `passt` and, optionally, `qemu`: + new network namespace using `pasta`, starts `passt` *and, optionally,* `qemu`: doc/demo.sh @@ -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) 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