Contributing

One of the pillars of this project is to make it easy to contribute back in any way. That can't happen if it is unclear how you can contribute back. This page exists to make that part clear to users, developers and others.

Before anything else

Read the community guidelines. There are two rules, and they apply everywhere the project happens: the chat channels, the code forge, issues and reviews. For those that want to see a Contributor's Covenant or something like that: I understand. At this point in time I don't want to spend my time (yet) on writing one out, or even using one that is pre-baked. The rules I have set are more strict than any Contributor's covenant could ever place, because they omit the parts that people try to abuse. At some point in the future, we can adopt one. How the rules are applied is mostly irrelevant when the project is run by a single person.

Getting help

On our Discord (invite) there's a Support channel where you can post support questions, bugs, suggestions or anything. While not an official support channel (yet), I highly encourage everyone to use this so that your issues can be resolved and active community members can help out. If you'd rather use IRC, we're in #urproject on irc.libera.chat. The community page has the details. The Forgejo instance can additionally be used to open issues, even if they are support requests.

Before asking, the documentation may already have the answer. The user guides cover installing, maintaining and building things start to finish, and the manual pages are the same ones installed on your system.

Submitting bugs

Our Forgejo instance hosts git repositories that have split out content (registries) from code. This is an ideal place to file per-recipe/package issues, or per code project. Each git repository has issues enabled. See where things live below to pick the right one.

Security issues are different. Don't file those in a public issue tracker; see the security page for how to reach me.

Submitting requests

Either the Discord or the issue tracker will work well! A request for a new package goes in the common registry.

Submitting patches

You can OAuth register with your GitHub, GitLab or Codeberg account on code.foo-projects.org and fork any of the projects. All code contributions are welcome.

AI and LLM use

I haven't posted an official AI/LLM usage policy yet. Consider it to be the same as the Linux kernel for the time being: it's allowed, but you are responsible for all your code submissions.

Where things live

All our code is hosted with Forgejo at code.foo-projects.org. The content and the code are split up:

• ur-project: the build system (dispatcher), the package manager (pkg) and composition. One Rust codebase, which both builds the distro and consumes it.
• registry-base: the recipes for the floor. With a copy of base you can make a new version of base without requiring anything else.
• registry-common: for now, just everything else.
• compositions: how packages are combined and shaped into images, the container, cloud, live USB, ISO and WSL images among them.
• boot-manager, ca-trust, instance-setup and flagger: the system software. See the code page for what each one does.

Working on recipes and packages

A recipe is the identity of how a package gets built, and what it is. It's like your grandmother's collection of cooking recipes: it lists the ingredients, and amounts, but it's largely devoid of detailed instructions on how to cook it. The autobuilder takes care of the rest. The recipe format post goes through what's in one.

The smallest unit of change takes almost no effort to start. You can test a recipe change in steps that grow with the size of the change:

• Local package builds. All you need is the pkg tool that is already on your system. Follow Building local packages, or watch the video of a local build first.
• Your own build system. One has just to install the package through pkg and call sudo dispatch init. You get a local dev registry that builds on top of the official repositories, with gates, review and automatic rebuilds. Deploying the build system walks through it.

On making modifications explains the tiers in full, from a single local package up to an independent OS.

Working on the code

All the code lives in git on our Forgejo instance; the list above shows which repository holds what. The build system, the package manager and composition are all in ur-project, and each piece of system software has a repository of its own, described on the code page.

Sending a patch works the same way for every one of them: sign in, fork the repository, and open a pull request with your change against it. See submitting patches for signing in, and AI and LLM use if a tool helped you write it.

Everything is written in Rust. Fe₂O₃.nH₂O has the reasoning.

Working on the documentation

Everything under /docs/ is a Markdown file. The manual pages are generated in the component repositories and copied in verbatim, so a fix to a manual page goes to the component's repository, not to this site.

Licensing

The Ur Project is Open Source and licensed largely under the GPL-3.0-or-later license. Contributions are accepted under the license of the repository they go to.