My first open source contribution
For a long time, my approach to side projects was simple: have an idea, build a tool. Over the years I started quite a few of them. Looking back, most of these ideas were not particularly special. They solved problems that others had already solved, often better. On top of that, I usually combined a new project with learning a new language. When I built Synapse in Go, I noticed how demotivating that combination can be: as soon as the project grows beyond a toy, you spend more time fighting the language than working on the actual problem.
So a few weeks ago I decided to change my approach. Instead of starting yet another project of my own, I wanted to contribute to existing open source projects. Projects that are actually used, where a small change has a real effect.
Choosing a project
My criteria were straightforward. The project should be easy to get into, but it should also matter. Ideally something I come across in my daily work. I ended up with uutils/coreutils, a reimplementation of the GNU coreutils in Rust. These are the tools everyone uses dozens of times a day without thinking about it: ls, cp, cat, sort, and many more. I use them every day, and I think reimplementing them in Rust is an important step: it gives these decades-old tools a modern, memory-safe foundation that can be maintained and refactored for many years to come.
So one evening I sat down and asked myself: what is the best way to get started? I browsed through the issues, especially the ones labelled "good first issue", and found a few that looked interesting. Before committing to one of them, though, I wanted to make sure my setup actually works. So I forked the repository, cloned it, and checked that the project builds and the tests pass:
cargo build
cargo test
Everything should be green. After all, main is supposed to be in a working state. It was not.
A red test on a clean main
One test failed on my machine:
#[test]
#[cfg(unix)]
fn test_stdbuf_reports_signalled_command() {
// SIGQUIT (3) rather than the usual SIGTERM, so the expected 131 cannot be
// confused with a status the shell would produce on its own.
new_ucmd!()
.args(&["-o0", "sh", "-c", "kill -QUIT $$"])
.fails_with_code(131);
}
The test checks that stdbuf correctly reports a child process that was killed by a signal. It starts a shell that sends SIGQUIT to itself and expects the exit code 131. On Unix, a process terminated by a signal is reported with the exit code 128 + signal number, and SIGQUIT is signal 3, hence 131.
On my machine, the test got 0 instead. The shell did not die at all.
Works on their machine
The reason turned out to be the distribution. I am running CachyOS, which is Arch-based. On Arch, /bin/sh is a symlink to bash. On Debian and Ubuntu, which most CI systems run on, /bin/sh is dash.
That difference matters here, because the bash manual is very explicit about it:
In all cases, bash ignores SIGQUIT.
So when bash runs as sh -c "kill -QUIT $$", it simply ignores the signal, finishes the command, and exits with 0. Dash does not ignore SIGQUIT, terminates, and the test passes. The test was not wrong in what it wanted to verify. It just made an assumption about /bin/sh that does not hold on every system.
The fix
The solution was to use a signal that no shell can ignore: SIGKILL. It cannot be caught, blocked, or ignored, and it is signal 9 on every Unix system. The expected exit code therefore becomes 128 + 9 = 137:
#[test]
#[cfg(unix)]
fn test_stdbuf_reports_signalled_command() {
- // SIGQUIT (3) rather than the usual SIGTERM, so the expected 131 cannot be
- // confused with a status the shell would produce on its own.
+ // SIGKILL (9 on every Unix) because no process can ignore or catch it, so
+ // the shell is guaranteed to die from it. Other signals are not reliable
+ // here: bash, when it is /bin/sh, ignores SIGQUIT for `sh -c`, and any
+ // signal ignored by the parent is inherited as ignored.
new_ucmd!()
- .args(&["-o0", "sh", "-c", "kill -QUIT $$"])
- .fails_with_code(131);
+ .args(&["-o0", "sh", "-c", "kill -KILL $$"])
+ .fails_with_code(137);
}
The last line of the comment covers a second, more subtle point: a signal that is ignored by a parent process stays ignored in its children, even across exec. So even with a shell that does not ignore a signal itself, the environment the tests run in (a terminal, a CI runner, a container) could still make the test flaky. With SIGKILL, that whole class of problems disappears.
From issue to merge
I first opened an issue describing the failing test and its cause, followed by a pull request with the fix. I was a bit nervous about it. It was my first pull request to a project I had no prior connection to, and you never quite know how maintainers react to someone new showing up.
I need not have worried. The review went through without a single finding, and the pull request was merged quickly. The maintainers were friendly and welcoming throughout. For a first contribution, I could not have wished for a smoother experience.
What I took away from it
This is obviously a tiny change: one signal and one number. But I learned a few things from it:
- Run the tests before you change anything. If I had started working on an issue right away, I would have assumed my changes broke the test and spent a long time looking in the wrong place.
- Your machine is part of the test environment. CI typically runs on Ubuntu. Contributors run on everything. A test that only passes on one distribution is a test with a hidden dependency.
- Small fixes are real contributions. Every new contributor on an Arch-based system would have hit the same red test on their first
cargo test. Removing that hurdle makes onboarding a bit smoother for the next person.
What's next
My original plan was never to fix a test. I wanted to work on actual functionality. That is exactly what comes next, although not in coreutils itself: uutils also maintains util-linux, a Rust reimplementation of tools like dmesg, lsblk, or findmnt. I volunteered to implement flock there, the small utility for managing file locks from shell scripts. A bigger step than a one-line test fix, and I am looking forward to it.
If you have been thinking about contributing to open source but don't know where to start: clone a project you use, run the tests, and see what happens. Sometimes your first contribution finds you before you find it.