October 2025 Posting - oils-for-unix/oils GitHub Wiki

Related: October 2025 Reply

Hello! I posted a request for help yesterday, and got a number of e-mails!

I'm going review each mail and respond. But I'll also include a link to this page, which includes info relevant to everyone who's interested.

(Note: this page may be continually updated, as I respond to e-mails.)

Details

  • Language Engineer
    • A primary goal of our NLnet grants is to get more people involved in the Oils code
    • Oils is a traditional AST / tree-walk interpreter in many ways -- I describe it as Crafting Interpreters Plus ~30 Unix System Calls
    • It's also pretty elaborate, and some things are specific to the shell
  • Debugger of Other People’s Cursed Shell Programs
    • A great way to get familiar with the code is to debug cases where OSH behaves differently than other shells, like bash or busybox ash. This can be hard!
  • Writer
    • We also want to pay people to tell others about what they're doing!
    • This can help attract contributors, and it also makes the project understandable to funders like NLnet
    • We take writing seriously -- it is normal for writing about a bug to take longer than finding and fixing it
    • Some contributors want to improve their technical writing skills, so this is a nice opportunity to be paid for self-improvement.

Note: not everyone has to wear all these hats. But if you only wear one hat, you might find that the project doesn't have anything for you to do at a given moment. Sometimes our progress is bottlenecked on different things

But we appreciate all contributions! Even if sporadic

Funding

We kicked off the 50K euro grant in August, and so far we've paid out 5K euros (10 percent).

The funding technically lasts a year, until August 2026.

Based on current progress, we might be able to get more funding. If we get down to the last Alpine bugs in 6 or 9 months, we could apply for another NLnet grant to do the same thing with Debian, so we have more funding. (There were 3 grants before this, so totaling 150K euros)

My long term goal is for others to be able to apply for grants to work on Oils. I will help on the technical side, but I'd like for contributors to be able to set goals independently, without being blocked or bottlenecked by whatever I happen to be doing at a given moment.

Details About Payment

As mentioned, for the 4th grant, contributors are being paid 50 euros/hour. The hours are self-reported, and include meetings, debugging, testing, writing, etc. as well as writing code.

NLnet pays you directly, in increments of 2500 euros (which would be 50 hours). But we can also pay out of Github sponsors, and we recently received a $4K donation, which I mention in the upcoming blog post.

NLnet Prefers to Pay Contributors Outside the USA

NLnet has requested that 60% of the funds (30K euros) go to non-US contributors, leaving 20K euros for US contributors.

(Note: I live in the USA, so I am part of the disfavored group! That is OK with me)

Correction

In the ad, I said

Anyone who's not “scared” of these bugs is probably a good fit, and you can do as much or as little as you like.

But "as little as you like" is probably not true :-/

This is because we don't want to create administrative overhead for NLnet by paying 10 different people 200 euros each.

We would like to pay each person at least 2500 euros. So technically, it is a slight issue if you end up doing too little :-)

So there is perhaps a bit of an issue where we have to "estimate" ahead of time whether a given contributor can put in 50 hours that advance the goals of the project (reducing bugs to test cases, fixing bugs, publishing good writing)

Clarification: Debugging is Crucial, But Language Engineering is Too

i.e. a language engineer has worked on the internals of a programming language

I emphasized debugging because some people think that working on a programming language is very fun and exciting :-)

It is, but it's also grinding through obscure test cases! And then generalizing to a clean solution.

So it's a good sign if you can think in both ways: in terms of concrete bugs, and in terms of a clean language implementation (there tend to be many trees, graphs, and stacks). We also have a little compiler and an associated GC runtime: the "mycpp" tool that translates typed Python to C++.

Dilemma for Contributors

Our funding situation may create a dilemma / risk for contributors. It's hard to tell if you'll be able to help the project, and advance its goals, without first spending a bunch of time on it!

And I also get a lot of inbound interest about the project. It's hard for me to tell if contributors will stick around.

Though that's one reason I chose these very concrete bug fixes to advertise. We have mostly the hard bugs left, and if you can fix a bug, or reduce it to a small test case, then you've certainly contributed.

The sections below may help you self-select into working on Oils.

FAQ: How do I know if I can contribute?

The Most Important Criteria

You actually want to use OSH and/or YSH !!

That is, part of the motivation should be to solve your own problems. This isn't a normal job where you commit code and then someone else uses it!

You should definitely have written a shell script before, probably substantial ones.

(Context: some people are attracted to the project because we're doing things to a high standard, and applying some good ideas. But it's also important to have real use cases that motivate your work.)

3 Good Signs

I mentioned the bugs linked from these pages:

If you want to ask questions about these pages, that's a good sign!

If you join Zulip, and you ask good questions on the many threads, that's also a good sign!

As with other open source projects, it could be that more than 50% of the time / work is following different discussions. And finding work yourself.

Being able to set up a dev env is a good sign too!

  • Contributing
    • I get wide reactions -- some people tell me that it is nice and worked the first time. Other people say: "why do I have to download and compile all this stuff?" :-)
    • But it should take 5-10 minutes on most Debian-ish Linux machines, I believe, and all current contributors have it set up.

Creating a Unix shell seems to require a lot of background knowledge, and there is a lot of it buried in the Oils project. We would like to spread that knowledge to interested people!

Good Sign: The Blog is Interesting

If my posts on #parsing-shell are interesting subject matter: https://www.oilshell.org/blog/tags.html?tag=parsing-shell#parsing-shell

We use a particular style of parsing to "tame" the complexity of shell.

Good Sign: Reasoning By Sets

We use "exhaustive reasoning" with regular languages and algebraic data types.

We use some informal mathematical reasoning, again to "tame" the complexity of shell.

Where Contributors Have Problems

This older wiki page I mentioned in the posting has more info on self-selecting: Where Contributors Have Problems

This Job is Unusual / Informal

I'm actually surprised by how many people responded to my ad! :-) From both lobste.rs and Hacker News

Sometimes I describe Oils as a "luxury" project :-) Unlike many software engineering jobs, we have the luxury of doing things to a high standard

It's definitely a part time project, because we don't have a lot of funding, and occasionally things get bottlenecked

Problems / Warnings

It's mostly the hard bugs that are left!

For example, the discussion on Zulip about bug 2335

Some Tasks Are Bottlenecked On Me

A goal of the NLnet grants is to reduce this problem! And we have specific milestones for it, like writing a dev guide.

There's a ton to read: Zulip, Github Bugs, Blog Posts, ...

Many people get overwhelmed by Zulip!

I regret that this this is the case, but the subject matter is inherently specialized and dense.

If you try to follow say the Rust project, you will experience a similar or greater amount of overwhelming detail.

Concrete Examples of Work

dtc package test failure -> printf %b bug in OSH -> Lexer Fix

We start with failures from the regtest/aports harness, which I call symptoms.

Blog Post: Links to Explain Oils in 2025

TODO: I have a draft, and plan to publish this soon.

Links

Asking questions on Zulip is always welcome!