- dev - passt

passt: new version 2025_09_19.623dbf6 available
by Stefano Brivio 20 Sep '25

20 Sep '25

The new version with tag 2025_09_19.623dbf6 includes the following changes: 623dbf6 Add --stats option to display event statistics ad4aae7 netlink: Drop nexthop state flags from routes we duplicate 080f176 Add CONTRIBUTING.md c66be2c selinux: add missing file contexts for Podman fd1bcc3 selinux: add container_var_run_t type transition 6f23cb9 dhcp: Fix coding style violations in dhcp() function 1f22fde Improve clarity of comment e2920e3 Send an initial ARP and NDP request to resolve the guest IP address 142b3d8 Fix --no-icmp description and make it imply --no-ndp 07cb07d Introduce constant MAC_BROADCAST fc0affc Show debug message whenever we observe a new guest MAC address https://passt.top/passt/log/?qt=range&q=2025_09_11.6cbcccc..2025_09_19.623d… Packages: - Alpine Linux: https://pkgs.alpinelinux.org/packages?name=passt - Arch Linux: https://www.archlinux.org/packages/extra/x86_64/passt/ https://archlinuxarm.org/packages/aarch64/passt https://archlinuxarm.org/packages/armv7h/passt - Chimera: https://pkgs.chimera-linux.org/packages?name=passt - Clear Linux: https://github.com/clearlinux-pkgs/passt/ - Copr (CentOS Stream, EPEL, Fedora, Mageia): https://copr.fedorainfracloud.org/coprs/sbrivio/passt/build/9584424/ permanent mirror: https://passt.top/builds/copr/0^20250919.g623dbf6/ - Debian tracker: https://tracker.debian.org/pkg/passt - Fedora updates: https://bodhi.fedoraproject.org/updates/?packages=passt - Gentoo versions: https://packages.gentoo.org/packages/net-misc/passt - GNU Guix: https://packages.guix.gnu.org/packages/passt/ - Homebrew: https://formulae.brew.sh/formula/passt - NixOS: https://github.com/NixOS/nixpkgs/tree/nixos-unstable/pkgs/by-name/pa/passt - openSUSE: https://software.opensuse.org/package/passt - OpenMandriva: https://github.com/OpenMandrivaAssociation/passt/tree/master - PLD Linux: https://git.pld-linux.org/cgi-bin/gitweb.cgi?p=packages/passt.git - Solus: https://github.com/getsolus/packages/tree/main/packages/p/passt - Ubuntu tracker: https://launchpad.net/ubuntu/+source/passt - Void Linux: https://voidlinux.org/packages/?q=passt - Static builds: - Package for other RPM-based distributions, x86_64 only: https://passt.top/builds/latest/x86_64/passt-g623dbf6-1.x86_64.rpm - x86_64 static binaries: https://passt.top/builds/latest/x86_64/ - Debian package, from x86_64 static build: https://passt.top/builds/latest/x86_64/passt_623dbf6-1_all.deb -- Stefano

1 0

passt: new version 2025_09_19.623dbf6 available
by Stefano Brivio 20 Sep '25

20 Sep '25

The new version with tag 2025_09_19.623dbf6 includes the following changes: 623dbf6 Add --stats option to display event statistics ad4aae7 netlink: Drop nexthop state flags from routes we duplicate 080f176 Add CONTRIBUTING.md c66be2c selinux: add missing file contexts for Podman fd1bcc3 selinux: add container_var_run_t type transition 6f23cb9 dhcp: Fix coding style violations in dhcp() function 1f22fde Improve clarity of comment e2920e3 Send an initial ARP and NDP request to resolve the guest IP address 142b3d8 Fix --no-icmp description and make it imply --no-ndp 07cb07d Introduce constant MAC_BROADCAST fc0affc Show debug message whenever we observe a new guest MAC address https://passt.top/passt/log/?qt=range&q=2025_09_11.6cbcccc..2025_09_19.623d… Packages: - Alpine Linux: https://pkgs.alpinelinux.org/packages?name=passt - Arch Linux: https://www.archlinux.org/packages/extra/x86_64/passt/ https://archlinuxarm.org/packages/aarch64/passt https://archlinuxarm.org/packages/armv7h/passt - Chimera: https://pkgs.chimera-linux.org/packages?name=passt - Clear Linux: https://github.com/clearlinux-pkgs/passt/ - Copr (CentOS Stream, EPEL, Fedora, Mageia): https://copr.fedorainfracloud.org/coprs/sbrivio/passt/build/9584424/ permanent mirror: https://passt.top/builds/copr/0^20250919.g623dbf6/ - Debian tracker: https://tracker.debian.org/pkg/passt - Fedora updates: https://bodhi.fedoraproject.org/updates/?packages=passt - Gentoo versions: https://packages.gentoo.org/packages/net-misc/passt - GNU Guix: https://packages.guix.gnu.org/packages/passt/ - Homebrew: https://formulae.brew.sh/formula/passt - NixOS: https://github.com/NixOS/nixpkgs/tree/nixos-unstable/pkgs/by-name/pa/passt - openSUSE: https://software.opensuse.org/package/passt - OpenMandriva: https://github.com/OpenMandrivaAssociation/passt/tree/master - PLD Linux: https://git.pld-linux.org/cgi-bin/gitweb.cgi?p=packages/passt.git - Solus: https://github.com/getsolus/packages/tree/main/packages/p/passt - Ubuntu tracker: https://launchpad.net/ubuntu/+source/passt - Void Linux: https://voidlinux.org/packages/?q=passt - Static builds: - Package for other RPM-based distributions, x86_64 only: https://passt.top/builds/latest/x86_64/passt-g623dbf6-1.x86_64.rpm - x86_64 static binaries: https://passt.top/builds/latest/x86_64/ - Debian package, from x86_64 static build: https://passt.top/builds/latest/x86_64/passt_623dbf6-1_all.deb -- Stefano

1 0

passt: new version 2025_09_19.623dbf6 available
by Stefano Brivio 20 Sep '25

20 Sep '25

The new version with tag 2025_09_19.623dbf6 includes the following changes: 623dbf6 Add --stats option to display event statistics ad4aae7 netlink: Drop nexthop state flags from routes we duplicate 080f176 Add CONTRIBUTING.md c66be2c selinux: add missing file contexts for Podman fd1bcc3 selinux: add container_var_run_t type transition 6f23cb9 dhcp: Fix coding style violations in dhcp() function 1f22fde Improve clarity of comment e2920e3 Send an initial ARP and NDP request to resolve the guest IP address 142b3d8 Fix --no-icmp description and make it imply --no-ndp 07cb07d Introduce constant MAC_BROADCAST fc0affc Show debug message whenever we observe a new guest MAC address https://passt.top/passt/log/?qt=range&q=2025_09_11.6cbcccc..2025_09_19.623d… Packages: - Alpine Linux: https://pkgs.alpinelinux.org/packages?name=passt - Arch Linux: https://www.archlinux.org/packages/extra/x86_64/passt/ https://archlinuxarm.org/packages/aarch64/passt https://archlinuxarm.org/packages/armv7h/passt - Chimera: https://pkgs.chimera-linux.org/packages?name=passt - Clear Linux: https://github.com/clearlinux-pkgs/passt/ - Copr (CentOS Stream, EPEL, Fedora, Mageia): https://copr.fedorainfracloud.org/coprs/sbrivio/passt/build/9584424/ permanent mirror: https://passt.top/builds/copr/0^20250919.g623dbf6/ - Debian tracker: https://tracker.debian.org/pkg/passt - Fedora updates: https://bodhi.fedoraproject.org/updates/?packages=passt - Gentoo versions: https://packages.gentoo.org/packages/net-misc/passt - GNU Guix: https://packages.guix.gnu.org/packages/passt/ - Homebrew: https://formulae.brew.sh/formula/passt - NixOS: https://github.com/NixOS/nixpkgs/tree/nixos-unstable/pkgs/by-name/pa/passt - openSUSE: https://software.opensuse.org/package/passt - OpenMandriva: https://github.com/OpenMandrivaAssociation/passt/tree/master - PLD Linux: https://git.pld-linux.org/cgi-bin/gitweb.cgi?p=packages/passt.git - Solus: https://github.com/getsolus/packages/tree/main/packages/p/passt - Ubuntu tracker: https://launchpad.net/ubuntu/+source/passt - Void Linux: https://voidlinux.org/packages/?q=passt - Static builds: - Package for other RPM-based distributions, x86_64 only: https://passt.top/builds/latest/x86_64/passt-g623dbf6-1.x86_64.rpm - x86_64 static binaries: https://passt.top/builds/latest/x86_64/ - Debian package, from x86_64 static build: https://passt.top/builds/latest/x86_64/passt_623dbf6-1_all.deb -- Stefano

1 0

[PATCH] Add --stats option to display event statistics
by Laurent Vivier 19 Sep '25

19 Sep '25

Introduce a new --stats DELAY option that displays event statistics tables showing counts by epoll event type. Statistics are printed to stderr with a minimum delay between updates, and only when events occur. Signed-off-by: Laurent Vivier <lvivier(a)redhat.com> --- conf.c | 6 ++++++ passt.1 | 6 ++++++ passt.c | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ passt.h | 1 + 4 files changed, 77 insertions(+) diff --git a/conf.c b/conf.c index 02e903b5cf70..9aba27cef806 100644 --- a/conf.c +++ b/conf.c @@ -835,6 +835,8 @@ static void usage(const char *name, FILE *f, int status) "\n" " -d, --debug Be verbose\n" " --trace Be extra verbose, implies --debug\n" + " --stats DELAY Display events statistics\n" + " minimum DELAY seconds between updates\n" " -q, --quiet Don't print informational messages\n" " -f, --foreground Don't run in background\n" " default: run in background\n" @@ -1480,6 +1482,7 @@ void conf(struct ctx *c, int argc, char **argv) {"repair-path", required_argument, NULL, 28 }, {"migrate-exit", no_argument, NULL, 29 }, {"migrate-no-linger", no_argument, NULL, 30 }, + {"stats", required_argument, NULL, 31 }, { 0 }, }; const char *optstring = "+dqfel:hs:F:I:p:P:m:a:n:M:g:i:o:D:S:H:461t:u:T:U:"; @@ -1708,6 +1711,9 @@ void conf(struct ctx *c, int argc, char **argv) die("--migrate-no-linger is for vhost-user mode only"); c->migrate_no_linger = true; + break; + case 31: + c->stats = strtol(optarg, NULL, 0); break; case 'd': c->debug = 1; diff --git a/passt.1 b/passt.1 index af5726a7f1c5..d5cde2c424d0 100644 --- a/passt.1 +++ b/passt.1 @@ -84,6 +84,12 @@ Be verbose, don't log to the system logger. .BR \-\-trace Be extra verbose, show single packets. Implies \fB--debug\fR. +.TP +.BR \-\-stats " " \fIDELAY\fR +Display events statistics with a +minimum \fIDELAY\fR seconds between updates. If there is no event, +statistics are not displayed. + .TP .BR \-q ", " \-\-quiet Don't print informational messages. diff --git a/passt.c b/passt.c index a4ec115d1784..afd7f709e58a 100644 --- a/passt.c +++ b/passt.c @@ -83,6 +83,31 @@ char *epoll_type_str[] = { static_assert(ARRAY_SIZE(epoll_type_str) == EPOLL_NUM_TYPES, "epoll_type_str[] doesn't match enum epoll_type"); +char *epoll_type_tag[] = { + [EPOLL_TYPE_TCP] = "TCP", + [EPOLL_TYPE_TCP_SPLICE] = "TCPSPL", + [EPOLL_TYPE_TCP_LISTEN] = "TCPLSN", + [EPOLL_TYPE_TCP_TIMER] = "TCPTMR", + [EPOLL_TYPE_UDP_LISTEN] = "UDPLSN", + [EPOLL_TYPE_UDP] = "UDP", + [EPOLL_TYPE_PING] = "PING", + [EPOLL_TYPE_NSQUIT_INOTIFY] = "INOTF", + [EPOLL_TYPE_NSQUIT_TIMER] = "TIMER", + [EPOLL_TYPE_TAP_PASTA] = "PASTA", + [EPOLL_TYPE_TAP_PASST] = "PASST", + [EPOLL_TYPE_TAP_LISTEN] = "TAPLSN", + [EPOLL_TYPE_VHOST_CMD] = "VUCMD", + [EPOLL_TYPE_VHOST_KICK] = "VUKICK", + [EPOLL_TYPE_REPAIR_LISTEN] = "REPLSN", + [EPOLL_TYPE_REPAIR] = "REPAIR", +}; +static_assert(ARRAY_SIZE(epoll_type_tag) == EPOLL_NUM_TYPES, + "epoll_type_tag[] doesn't match enum epoll_type"); + +struct passt_stats { + unsigned long events[EPOLL_NUM_TYPES]; +}; + /** * post_handler() - Run periodic and deferred tasks for L4 protocol handlers * @c: Execution context @@ -174,6 +199,42 @@ static void exit_handler(int signal) _exit(EXIT_SUCCESS); } +/** + * print_stats() - Print event statistics table to stderr + * @c: Execution context + * @stats: Event counters + * @now: Current timestamp + */ +static void print_stats(const struct ctx *c, const struct passt_stats *stats, + const struct timespec *now) +{ + int i; + static struct timespec before; + long long elapsed_ns; + + if (!c->stats) + return; + + elapsed_ns = (now->tv_sec - before.tv_sec) * 1000000000LL + + (now->tv_nsec - before.tv_nsec); + + if (elapsed_ns < c->stats * 1000000000LL) + return; + + before = *now; + + /* table header */ + FPRINTF(stderr, "\t"); + for (i = 1; i < EPOLL_NUM_TYPES; i++) + FPRINTF(stderr, "%6s\t", epoll_type_tag[i]); + FPRINTF(stderr, "\n"); + /* main loop */ + FPRINTF(stderr, "MAIN\t"); + for (i = 1; i < EPOLL_NUM_TYPES; i++) + FPRINTF(stderr, "%6lu\t", stats->events[i]); + FPRINTF(stderr, "\n"); +} + /** * main() - Entry point and main loop * @argc: Argument count @@ -196,6 +257,7 @@ int main(int argc, char **argv) struct rlimit limit; struct timespec now; struct sigaction sa; + struct passt_stats stats = { 0 }; if (clock_gettime(CLOCK_MONOTONIC, &log_start)) die_perror("Failed to get CLOCK_MONOTONIC time"); @@ -362,6 +424,8 @@ loop: /* Can't happen */ ASSERT(0); } + stats.events[ref.type]++; + print_stats(&c, &stats, &now); } post_handler(&c, &now); diff --git a/passt.h b/passt.h index 3ffc19fdae05..283e7c8a832c 100644 --- a/passt.h +++ b/passt.h @@ -248,6 +248,7 @@ struct ctx { enum passt_modes mode; int debug; int trace; + int stats; int quiet; int foreground; int nofile; -- 2.50.1

2 1

[PATCH] netlink: Drop nexthop state flags from routes we duplicate
by Stefano Brivio 19 Sep '25

19 Sep '25

The kernel doesn't like those (EINVAL) on RTM_NEWROUTE, as they are flags representing states, not configuration. Link: https://github.com/containers/podman/discussions/27104 Signed-off-by: Stefano Brivio <sbrivio(a)redhat.com> --- netlink.c | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/netlink.c b/netlink.c index 8f82e73..c436780 100644 --- a/netlink.c +++ b/netlink.c @@ -565,6 +565,11 @@ int nl_route_dup(int s_src, unsigned int ifi_src, if (nh->nlmsg_type != RTM_NEWROUTE) continue; + /* nexthop state flags don't apply to freshly created routes, + * and the kernel will refuse our route if they are set. + */ + rtm->rtm_flags &= ~RTNH_COMPARE_MASK; + for (rta = RTM_RTA(rtm), na = RTM_PAYLOAD(nh); RTA_OK(rta, na); rta = RTA_NEXT(rta, na)) { /* RTA_OIF and RTA_MULTIPATH attributes carry the -- 2.43.0

3 2

[PATCH v6 1/5]
by Volker Diels-Grabsch 19 Sep '25

19 Sep '25

This incorporates all feedback of v5, and the commits are slightly reordered so the comment of the last commit makes more sense.

3 13

[PATCH 1/2] selinux: add container_var_run_t type transition
by Paul Holzinger 18 Sep '25

18 Sep '25

In some cases the podman runroot directory used to be labelled container_var_run_t instead of user_tmp_t which was expected here. Starting with a recent container-selinux change the runroot is now always container_var_run_t so make the policy handle both types to allow for a better upgrade path where passt-selinux and container-selinux are not updated at the same time. Link: https://github.com/containers/container-selinux/pull/405 Link: https://github.com/containers/podman/issues/26473 Signed-off-by: Paul Holzinger <pholzing(a)redhat.com> --- contrib/selinux/pasta.te | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/contrib/selinux/pasta.te b/contrib/selinux/pasta.te index c0a1e9b..24e58c8 100644 --- a/contrib/selinux/pasta.te +++ b/contrib/selinux/pasta.te @@ -96,6 +96,7 @@ require { role staff_r; role user_r; type container_runtime_t; + type container_var_run_t; type container_t; type systemd_user_runtimedir_t; } @@ -242,8 +243,12 @@ type_transition container_runtime_t pasta_exec_t : process pasta_t; allow container_runtime_t pasta_t:process transition; # Label the user network namespace files +# Note podman files used to be user_tmp_t but now are container_var_run_t since +# https://github.com/containers/container-selinux/issues/404. type_transition container_runtime_t user_tmp_t : dir ifconfig_var_run_t "netns"; +type_transition container_runtime_t container_var_run_t : dir ifconfig_var_run_t "netns"; type_transition container_runtime_t user_tmp_t : dir ifconfig_var_run_t "rootless-netns"; +type_transition container_runtime_t container_var_run_t : dir ifconfig_var_run_t "rootless-netns"; allow pasta_t ifconfig_var_run_t:dir { add_name open rmdir write }; allow pasta_t ifconfig_var_run_t:file { create open write }; allow systemd_user_runtimedir_t ifconfig_var_run_t:dir rmdir; -- 2.51.0

2 5

[PATCH v3] Add CONTRIBUTING.md
by Yumei Huang 18 Sep '25

18 Sep '25

Signed-off-by: Yumei Huang <yuhuang(a)redhat.com> --- 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 <file1> <file2> ... + +* 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… + 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 <random(a)developer.example.org> + + 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(a)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(a)passt.top --cc=maintainer(a)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 <file1> <file2> ... + git commit --amend + git format-patch -v2 -o outgoing/ origin/master + +* Send the revised patches: + + git send-email --to=passt-dev(a)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#spli… + 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

3 2

[PATCH] dhcp: Fix coding style violations in dhcp() function
by Laurent Vivier 18 Sep '25

18 Sep '25

The dhcp() function wasn't following the inverted Christmas tree variable declaration ordering convention. Signed-off-by: Laurent Vivier <lvivier(a)redhat.com> --- dhcp.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dhcp.c b/dhcp.c index 012cec6c0d04..6b9c2e3b9e5a 100644 --- a/dhcp.c +++ b/dhcp.c @@ -311,10 +311,10 @@ int dhcp(const struct ctx *c, struct iov_tail *data) const struct ethhdr *eh; const struct iphdr *iph; const struct udphdr *uh; + struct msg m_storage; struct msg const *m; struct msg reply; unsigned int i; - struct msg m_storage; eh = IOV_REMOVE_HEADER(data, eh_storage); iph = IOV_PEEK_HEADER(data, iph_storage); -- 2.50.1

3 2

[PATCH v2] Add CONTRIBUTING.md
by Yumei Huang 18 Sep '25

18 Sep '25

Signed-off-by: Yumei Huang <yuhuang(a)redhat.com> --- 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 <file1> <file2> ... + +* 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… 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 <random(a)developer.example.org> + + 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(a)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(a)passt.top --cc=maintainer(a)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 <file1> <file2> ... + git commit --amend + git format-patch -v2 origin/master + +* Send the revised patches + + git send-email --to=passt-dev(a)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#spli… + 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

2 1