Anatomy of a Feature Contribution
Anatomy of a Feature Contribution
Participation is the lifeblood of Free Software, so it’s important for every project to show users how to participate and create opportunites for them to do so.
When you’re writing a feature suggestion for Project Resistor, focus on three items: the implementation, a user-facing summary of the feature, and a developer-facing description of the reason the feature belongs in the OS, rather than something users run as a container. This post walks through a realistic example (adding OpenShell to the AI Developer Desktop) to illustrate what a complete contribution looks like.
The Implementation
The implementation is the code that makes the feature work. In an Atomic desktop image, this typically means an install script called during the container build and any necessary changes to the main build script.
For OpenShell, the implementation consists of two files:
build_files/build.sh — A one-line addition to call the install
script during the image build.
build_files/install-openshell.sh — A self-contained install
script that downloads the OpenShell RPMs from a GitHub release,
verifies checksums, installs the packages, and enables the systemd
user services that start the gateway at login.
The install script is a simplified versionof OpenShell’s upstream
install.sh
The Feature Description
The feature description lives in features/openshell.md and is
written for users of the image. It answers: what does this
feature do for users?
---
layout: feature
name: "OpenShell"
status: "experimental"
---
OpenShell is an open-source runtime from NVIDIA that lets you
run AI coding assistants like Claude Code in sandboxed
environments with kernel-level isolation. It enforces controls
over file access, credentials, and network connections through
declarative YAML policies, so autonomous agents operate with
exactly the permissions they need and nothing more.
This file is automatically pulled into the Project Resistor website
during the site build, where it appears on the
Desktop Images page. The status field tells users how
mature the feature is. In this case, experimental signals that it’s
new and may change.
The feature description doesn’t explain how OpenShell is installed or why it belongs in the image. It focuses on what the user gets.
The PR Description
The PR description is written for the project maintainer who reviews the contribution. It answers a different question: why does this feature belong in the base image rather than something users install themselves?
For OpenShell, the answer involves technical constraints:
OpenShell depends on Linux kernel security modules (Landlock, seccomp) that operate at the kernel boundary and cannot enforce isolation from inside a nested container. It also needs direct access to the Podman socket to manage sandbox containers and relies on systemd user services for gateway lifecycle — neither of which work correctly in unprivileged containers.
Features that users can run as containers are often best left for users to download and run after installation, especially when there are numerous applications providing similar functionality, where the choice should be left up to the user.
The PR description is where you make the case that your feature genuinely requires host-level integration.
Finishing up
A complete feature contribution includes:
| Part | Question it answers |
|---|---|
| Implementation | How does this work? |
| Feature description | What does this do for users? |
| PR description | Why does this belong in the image? |
An example contribution can be seen in PR #6.