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=ZZRuQ+cF; 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 010F95A0271 for ; Wed, 17 Sep 2025 06:31:09 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1758083469; 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=fzs2CCh5SfJ+iQHfb003dCocvs2ICrW1urIWhJB3vSI=; b=ZZRuQ+cFXZ4zmIIxO2sxS1a5OcutA8sCGvw2EV22p8ujnUCtWIGPcx0zVHsYNVBmi6YgTh 2wx4XvHGmNn+NbXajEI4yl5KoF5fxW5AAKEhRTlzQbJ7CeW9vsXsIIjT3nhac8K9aMBQHw fpPDyuJyxzlL0RhOhjtfOP48ke06sFw= Received: from mail-ed1-f69.google.com (mail-ed1-f69.google.com [209.85.208.69]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-689-Y7FbslaPMryKZ3aqdePTcA-1; Wed, 17 Sep 2025 00:31:06 -0400 X-MC-Unique: Y7FbslaPMryKZ3aqdePTcA-1 X-Mimecast-MFC-AGG-ID: Y7FbslaPMryKZ3aqdePTcA_1758083466 Received: by mail-ed1-f69.google.com with SMTP id 4fb4d7f45d1cf-62f770119a0so980935a12.0 for ; Tue, 16 Sep 2025 21:31:06 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1758083465; x=1758688265; h=content-transfer-encoding:cc:to:subject:message-id:date:from :in-reply-to:references:mime-version:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=fzs2CCh5SfJ+iQHfb003dCocvs2ICrW1urIWhJB3vSI=; b=T0Gl0+saV6c0JjGBoQVxzrGvfzmY/6INJ1DfFbI05SXqi/2Qnvo4zN6a/eyQxRKRWi uehMU+ACCt2Jyu1AFFQY7+m9E5CiZxiplejDBjq+vXnnQtcbh/HNQuUUPELLbvGyhdDq mpXsu97Ku6jchtjcgs6rkmas0ABGZD9fsjYvGuM+BDiZurgkmM+zT3I1BvTyd9r5tLQG J0y7QfAyKLhOXUKGxU5dzCGJWsx1LwM+j++pCUqsO2x+6x/AfEdTjsR+QIoTDXuZT4Pg 6OQmi+KJUL1hox6bqdV85jzGAJTw/kIQ5KWVylB9AzXdbz+AGG8Y9ein3pplPnIxNhAf u5MA== X-Forwarded-Encrypted: i=1; AJvYcCVmvngVTEFWHrmKW0UGvcW/fIHlT3Y2Ttlq1cywT+DfZyHJE6mygTfhswuyu+T9HVV/441t+72Xr5M=@passt.top X-Gm-Message-State: AOJu0Yw7h/i0XSSoKfZGO1qXUJ+BbaSSJPFufFa/0fo19lVjRwUhZ1Hd ad4gYwKFWQM0R3WTmV3u4DsyhDoyndwe1b3Zgfrppm4gVNaYJ4ql3ElkjnwnSMiGMBFPzj9wOqJ YtYCiUsWuWFwPOD1brIu+QOUHUcrLOsq8iYjYt3BTXY+SLaOZtnPwrM0zDZOM1CSQXsQY9yq+Eo uJ+/e+1C7mmIxbRo5UyVLIYn5C4Hlf X-Gm-Gg: ASbGnctPqHIJPLNc+iXuyJlse1xOW1v9FPkT6Lj9Svt1Ro71ZbSpxyWSa4dRdGrcn/0 ztK8RxzNGMyGgb89EWNK9L96T5QIuzsHOyjhVaQuVSJAt7PsYSzaCmbrRmrmB6l+0uGcByZUjOu 6pDoyOBXFz7xZKlibmp+sBdg== X-Received: by 2002:a17:907:3da9:b0:b0c:b51b:821e with SMTP id a640c23a62f3a-b1bb5e571e4mr96547666b.9.1758083465458; Tue, 16 Sep 2025 21:31:05 -0700 (PDT) X-Google-Smtp-Source: AGHT+IEKt2TqCNirt2grTLFKckEnNLG2mT3OQGcjDkcIpv1KEZuQUF2i0rPmdc2pjep8rQciyIMty1ktyqRnhAwtbyM= X-Received: by 2002:a17:907:3da9:b0:b0c:b51b:821e with SMTP id a640c23a62f3a-b1bb5e571e4mr96545566b.9.1758083464946; Tue, 16 Sep 2025 21:31:04 -0700 (PDT) MIME-Version: 1.0 References: <20250912075423.19500-1-yuhuang@redhat.com> <20250915084330.75867c00@elisabeth> In-Reply-To: <20250915084330.75867c00@elisabeth> From: Yumei Huang Date: Wed, 17 Sep 2025 12:30:53 +0800 X-Gm-Features: AS18NWALS2_SNMpdMhdoIdXfM7GLmpEZk1iCqKi-JvK_axCkvV6KGwJ5Vrsn0YU Message-ID: Subject: Re: [PATCH] Add CONTRIBUTING.md To: Stefano Brivio X-Mimecast-Spam-Score: 0 X-Mimecast-MFC-PROC-ID: S5auKZZGrqQGRH2Fu1L0tGRIbjjJwYaJzg6gug5H5M4_1758083466 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable Message-ID-Hash: MTHEV3PCVGAAFZWHCDIFDN45MP6M4MQ4 X-Message-ID-Hash: MTHEV3PCVGAAFZWHCDIFDN45MP6M4MQ4 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 , 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: Thank you Stefano and David for the suggestions. Sent V2, please let me know if I miss anything. On Mon, Sep 15, 2025 at 2:43=E2=80=AFPM Stefano Brivio = wrote: > > 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 add= ing: > > > > > > * 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= =3Dheads#developers-certificate-of-origin > > [1] > > https://github.com/dgibson/dtc/blob/main/CONTRIBUTING.md#developers-cer= tificate-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-c= hanges > > > > + > > > + 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 wit= h `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=3Dpasst-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 wit= h `--cc`: > > > + > > > + git send-email --to=3Dpasst-dev@passt.top --cc=3Dmaintainer@exam= ple.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=3Dpasst-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). I will update test/README.md soon after I manage to run the full tests. > > 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 d= ifference. > > > -- > > > 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 > --=20 Thanks, Yumei Huang