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=PsHF6c9E; dkim-atps=neutral Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by passt.top (Postfix) with ESMTPS id 3CAE45A0271 for ; Mon, 15 Sep 2025 08:43:37 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1757918616; 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: in-reply-to:in-reply-to:references:references; bh=pYcXxskILtg2AUc9/RwW7CuLCdUfSvGWBaag9yIiMq0=; b=PsHF6c9EnxqSVxr/5b9iNOfYKPnylBjJMf2RPQaKa35SO1dadaabBLtsn9gPB4mf1nCIVq xuEBRQw7cnMh8LcSjtLqNnR5LQ+1WQ31LJYfJGH5lCxXNzoWNjFP2YkplCHI4hAXBIQtzJ ss2hTpgJ7o0o/WmTZ73BuIj78wo442k= Received: from mail-wm1-f69.google.com (mail-wm1-f69.google.com [209.85.128.69]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-411-QWpcrPA8NcGCGuCXZsMdCw-1; Mon, 15 Sep 2025 02:43:34 -0400 X-MC-Unique: QWpcrPA8NcGCGuCXZsMdCw-1 X-Mimecast-MFC-AGG-ID: QWpcrPA8NcGCGuCXZsMdCw_1757918613 Received: by mail-wm1-f69.google.com with SMTP id 5b1f17b1804b1-45f2f1a650dso1624795e9.2 for ; Sun, 14 Sep 2025 23:43:34 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1757918613; x=1758523413; h=content-transfer-encoding:mime-version:organization:references :in-reply-to:message-id:subject:cc:to:from:date:x-gm-message-state :from:to:cc:subject:date:message-id:reply-to; bh=pYcXxskILtg2AUc9/RwW7CuLCdUfSvGWBaag9yIiMq0=; b=Ve3LJz9kLi+x5gfML+mpQ2m7EBMHfJCtjerOyH+W3pUg2bgLvTT/y7eon33ERQxCzW D1yHlqM4Bg2SBqahG7DCHfyAkaD5ebrjNCRl20dIBDUQGEZsmjDpRUXam54ugZ25InUj 4yxQRE+B5AlxcFSlfnCrv8Tt8dB7DcCdCGPCWbldPofnR1cZq23E57LViGTFBJ3rjqPP 3cQiDrxUCTSAVc2Ol6rJ1f3yHF/uftoGhD/M+XvH6XQ52A9rtpFmozO0OSpGRTr6CEhR Q5rVpi3EZ9hXjrSc57QQJOvC3+nI3zlHLQY5C42utzh23mHMJfz6QWlwmyuYupFAQwYs RyDw== X-Gm-Message-State: AOJu0YzDhHyWfDWkJ1mBYIUR41UBbCw4K1v11gOF9CoPecJfXdpXY6fB xnezq/8mcV8UjlFY4UQh2QWq7yHAd/MQQOxtjIVfvizMUwJKjTJ3pTFKhH5XHGbNStrlnNTcE9f hGt1pr7u2l1wy2FwhTLg8YK/Qv9LzsA//F9ZQdz0H8fYjuuTDBpmv1w== X-Gm-Gg: ASbGncut2GDG5IMuXC6/TempUMpQ4wUALz18TDRucvJ+gO/GnDBqCXJAP81w6Hh9Xne tSCAPw2TdH8Ta4DJKOtGOh5vUNICz2hBOCDcanYl/yLiJQkI/3Labnjg0xT7lcO9vP8E0oWHxzM MFrC4BW+v1snN7Ow1QTACnogIc0U2bri2V3zdu6NJbCU8pTWfkPNFmQa+GJxDzy4ny0ZwnGtmpO PHfEw6uo7+RaokbrC8c28KUEd9yCnsGiGnbLEeJR6222wIsGslAYqWmGpQvBFaW3uF4fKLkhSxh FkNfysyVZwwMa9zP+PB25bPBZNoVC3cYs3CEvJ4OEda2ZHZbYIt8877YCmaqfAJcQmyo X-Received: by 2002:a05:600c:4453:b0:459:dde3:1a55 with SMTP id 5b1f17b1804b1-45f211f2fbemr125207295e9.24.1757918613017; Sun, 14 Sep 2025 23:43:33 -0700 (PDT) X-Google-Smtp-Source: AGHT+IHVUI6ref4GlzsshHEy8mMoKIfypFjS0CorGzMVhPpDuOlhbqqBUE3jIma84g9BRgkuNBzKXw== X-Received: by 2002:a05:600c:4453:b0:459:dde3:1a55 with SMTP id 5b1f17b1804b1-45f211f2fbemr125206965e9.24.1757918612463; Sun, 14 Sep 2025 23:43:32 -0700 (PDT) Received: from maya.myfinge.rs (ifcgrfdd.trafficplex.cloud. [176.103.220.4]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-45e037b922csm171602275e9.15.2025.09.14.23.43.31 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 14 Sep 2025 23:43:31 -0700 (PDT) Date: Mon, 15 Sep 2025 08:43:30 +0200 From: Stefano Brivio To: David Gibson , Yumei Huang Subject: Re: [PATCH] Add CONTRIBUTING.md Message-ID: <20250915084330.75867c00@elisabeth> In-Reply-To: References: <20250912075423.19500-1-yuhuang@redhat.com> Organization: Red Hat X-Mailer: Claws Mail 4.2.0 (GTK 3.24.49; x86_64-pc-linux-gnu) MIME-Version: 1.0 X-Mimecast-Spam-Score: 0 X-Mimecast-MFC-PROC-ID: scc-arUGkhHgrlvkvVzo8Hf6y7KeiuQD8P9obb1kXh8_1757918613 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Message-ID-Hash: 2ZDYXT2A4AXTATCPRSUZYN2KY7MD5WSF X-Message-ID-Hash: 2ZDYXT2A4AXTATCPRSUZYN2KY7MD5WSF X-MailFrom: sbrivio@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: passt-dev@passt.top 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: On top of David's comments: On Mon, 15 Sep 2025 12:10:54 +1000 David Gibson wrote: > On Fri, Sep 12, 2025 at 03:54:23PM +0800, Yumei Huang wrote: > > Signed-off-by: Yumei Huang > > 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`. This is not necessary, strictly speaking. In fact, a bit out of laziness, but also because I'm sometimes rebasing while working on more than one feature / issue in parallel, I work on the master branch most of the times. And while it's sometimes out of laziness, I can probably argue that in some cases it's actually faster. I would suggest to word this as a possibility, "You can decide to work ...". > > + > > +### 3. Make Changes and Commit > > + > > +* Edit the source code or documentation. > > + > > +* Stage your changes: > > + > > + git add ... > > + > > +* Commit with a clear message containing `Signed-off-by:` tag: What is a "clear" message? Almost nobody writes obscure messages on purpose, but people might be not aware of what we want in commit messages, which is roughly this: https://docs.kernel.org/process/submitting-patches.html#describe-your-changes > > + > > + git commit -s > > + > > + Commit message format: > > + > > + Subsystem: Brief summary (max ~50 chars) No, why 50? It's quite hard to do that. 80 is fine, and 80 shouldn't be a hard limit here (nice if it fits in a terminal, but sometimes it's impossible). We should make clear what "Subsystem" is, with an example. It's not really well defined, by the way, it's a loose "area" (one might want to say "tcp:" for tcp_buf.c changes, or maybe "tcp_buf:"... both are fine). > > + > > + More detailed explanation if needed, wrapped at 72 chars. > > + > > + Signed-off-by: Your Name > > + > > + If there are some references, use "Links: " tag for simplicity. This is for simplicity over other mechanisms (with Resolves: and Bugzilla: and whatnot), but by itself, adding tags is not something one does for simplicity. I'd say "just use Links: tags for anything". > > + > > +### 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. Or git format-patch -n, that is, if you want to format just three patches and not the whole branch (especially if you're working on master as I do), you can do git format-patch -3. > > + > > +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 Perhaps better to tell people to use '-o' and use a separate directory to send patches from. > > + > > +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 Actually, I slightly prefer what David is doing and what is (was?) commonly done for most Linux kernel subsystems, that is, the maintainer (myself) in To:, Cc: or To: list, Cc: others who should know. That's because if I'm in To:, that's an obvious sign I need to take action (review / apply). If I'm on Cc:, that's something I need to be aware of, but not necessarily take action myself. On the other hand, I don't want to have my email address hardcoded here, and having a MAINTAINERS file look overkill, so I'm fine with this. After all, it's as described at: https://passt.top/#contribute just, well, if you're reading this, here's a tip that can happily remain undocumented: add me in To:, and you'll get a slightly faster reaction from my side. > It might be worth mentioning git-publish > (https://github.com/stefanha/git-publish) as an easier way of doing > steps 4 & 5. It breaks two things if I recall correctly: - it adds a spurious line between tags and Signed-off-by: - it shortens the description of referenced commit with "...", that is, for example, Fixes: 0123456789ab ("very long description that never en...") and we don't want that (that's how it's done in the kernel). I planned to send a patch for the first one but couldn't quite understand where that comes from so I never took care of that. > > +### 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. Maybe add a reference to: https://docs.kernel.org/process/submitting-patches.html#split-changes ...even though we're not really strict about it. The git log is full of "While at it..." sentences, and it's fine if it saves effort without compromising ease of review. > > + > > +* Test your changes thoroughly. ...here should come the reference to test/README.md (which should be updated first). If running tests is too complicated, maybe mention running 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 or APIs. No APIs here. > > + > > +Thank you for helping improve passt! Your contributions make a big difference. > > -- > > 2.47.0 > > ...I'll probably have more comments and feel like adding more stuff at some point but I can also submit some stuff as a separate patch on top of a base you're creating. -- Stefano