Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
112 lines (76 loc) · 3.39 KB

CONTRIBUTING.md

File metadata and controls

112 lines (76 loc) · 3.39 KB

Contributing to chunkah

Getting started

chunkah is written in Rust so you'll need a Rust toolchain set up. It also uses just instead of the more common make.

To build chunkah and run unit tests:

just check

Your iteration loop as you're hacking on chunkah will likely be mostly this in early development.

There is also just checkall which runs additional checks/lints. Run this before submitting a PR.

e2e tests

To run the e2e tests, you first need to build the chunkah image locally. This can be done using

just buildimg --no-chunk

(The --no-chunk option skips the self-chunking step for faster builds.)

And then you can run e2e tests with

just test

It also supports running just some tests (e.g. just test reproducible).

Support tooling

There's also various development tools available to make it easier to debug/test code. Two are documented here, but definitely look at all the scripts in the tools/ directory.

just split

Helper to split an image using the Containerfile.splitter flow. Example usage:

just split quay.io/fedora/fedora -v

just diff

Helper to diff between two images, usually the original image and the result of passing it through chunkah. Example usage:

just diff quay.io/fedora/fedora-minimal localhost/fedora-minimal

AI-assisted contributions

This project heavily uses AI for development. This section sets clear expectations on using AI for contributions. The guidance below is inspired by Oxide's RFD 576 on using LLMs (the whole doc is definitely worth a read!).

You own what you submit

However the code was produced, the contributor bears full responsibility for it. AI is a tool; the human using it is accountable for the result. This means you MUST understand every line of code you submit and be able to explain the design decisions behind it.

Self-review is mandatory

DO NOT request reviews on AI-generated code you did not yourself review first. Check for correctness and clarity. If you wouldn't be comfortable defending a line of code in review, don't submit it. Failure to do this self-review and catching obvious AI slop during the review process wastes time and erodes trust.

Don't re-generate in response to review

You can use AI to help address review feedback, but it must be intentional and targeted to the review areas. DO NOT regenerate the whole contribution. The interdiff (the diff between the last reviewed patches and your addressing of them) must be in line with what reviewers expect given the feedback they gave.

Disclose AI usage

Disclosure of AI usage is recommended but not mandatory. The best way to disclose it is via an Assisted-by: trailer in your commit messages to indicate which AI tool was used. For example:

Assisted-by: Claude Opus 4.6

This isn't about shaming or gatekeeping (many/most commits in this repo are AI-assisted!). It's about providing useful context to make review easier, and to help us learn collectively about where AI assistance works well and where it doesn't.

The AGENTS.md file

The AGENTS.md file provides detailed guidance to AI coding agents working in this repository, including project architecture, coding conventions, and build commands. If you use an AI coding agent, make sure it has access to this file.