Basic Things

Speaking of READMEs, I like to try to have one in each directory. This naturally happens if you have modules or libraries in a repo, each with their own directory.

But even if you have a monolith with tons of HTTP controller classes, grouping them by domain and providing a guide to the domain is really nice when you're on an expedition through the codebase.

It's a place to take notes about decisions, introduce domain-relevant terms, collect links to further reading, etc. all stuff which helps people completely unfamiliar with the code, or jogs the memory if the author was you-from-the-past.

Great write up. I read through maybe half of the points and skipped to the end, bookmarked to come back and finish later.

I’d like if the author could elaborate a bit about the types of projects that influenced these guidelines. Roughly what constitutes a “large” project, were the projects open source, private/commercial, or a mix of both, does web/service platform vs. desktop/local platform have an impact on these, etc.

A great list! I'll have to keep this in mind for my projects. I think I have most of these covered, but a more definitive list is always welcome :)

nice article!

something that bit me recently was the spf13/cobra library's user website. the instructions for installation are wrong, and they have been wrong for 2 years! i had to scroll to the very bottom of a multi-page readme to find the correct installation instructions!

i find this article really useful and will likely be applying its takeaways to my repos immediately.

Regarding writing tools/tests/benchmarks in bash+Python, vs. writing tools in your main language:

I think we might eventually concede that something Debian-like is the “standard development environment” (at least for server side stuff, i.e. not iOS apps)

In this case, bash+Python is a non-issue. It works extremely reliably. That’s actually why I use it! Everything else seems to break, or it’s really slow (node.js is a very common alternative).

- Microsoft conceded this back in ~2017, by building Linux into their kernel with WSL, and providing Ubuntu on top

Yes bash + Python is bad on Windows (I have scars from it), but Microsoft agrees that the right place to solve that is in Windows :-)

- Every CI system runs Debian/Ubuntu

- Every hosting provider runs Debian/Ubuntu

- Every online dev env like gitpod.io provides Debian/Ubuntu

This is somewhat related to remote dev envs: https://lobste.rs/s/ucirlx/lapdev_self_hosted_remote_dev

One vision for https://www.oilshell.org/ is that the CI environment is the dev environment is the hosting environment.

Everything is just an equal node in a distributed system. BUT it’s more git like, in that you explicitly sync and work “locally”, wherever that is. You don’t have the network chatter and flakiness of “the cloud”.

---

Oils has a very large set of monotonically increasing properties too - https://www.oilshell.org/release/0.21.0/quality.html

All that is bash+Python that is run on every commit, and it’s extremely good at catching bugs and perf regressions.

I’m skeptical that any project has that level of quality automation written in pure Rust or Zig, and self-hosted. More likely it’s a bunch of cloud services with YAML.

Also a bunch of “hard-coded” toolchains that you can’t script with bespoke code. Like some shell commands in your package.json, which is just a worse way of writing a shell script.

---

Our quality process is all self-hosted, in the repo, and runs on both Github Actions and sourcehut - https://www.oilshell.org/release/0.21.0/pub/metrics.wwz/line...

(Although we need to unify the CI and release, because the release runs on 2 different real hardware machines, while CI is cloud only.)

bash and Python runs perfectly on Github Actions and sourcehut, with zero change. Containers also do.

Also, a main point Oils is that bash now has another highly compatible, spec-driven implementation – OSH. Having 2 independent implementations is something newer languages don’t have.

(copy of lobste.rs comment)