* ci: gate pull requests and share release caches * fix(ci): keep release caches restore only
6.2 KiB
Contributing to PaperCraft
Thanks for wanting to help. PaperCraft is an alpha, so there is plenty to do and the bar for a first contribution is low: a typo fix, a clearer error message, a missing test or a one-line bug fix are all welcome.
Please read RULES.md before writing code: it holds the standards a change is judged by. By taking part you agree to the Code of Conduct. Using an AI tool is fine; the AI usage policy says what you stay responsible for, and coding agents should read AGENTS.md.
Ways to help
- Report a bug or suggest a feature with an issue. A screenshot or a short recording helps; so does the project folder (or a page of it) that triggers the bug.
- Pick something from ROADMAP.md. Rows marked
todoorpartialare open. Say which one you are taking in an issue first, so two people do not build the same thing. - Improve the docs, skills or screenshots. docs/, skills/ and the README are as important as code.
- Review a pull request. A second pair of eyes is always useful.
Security problems do not go in public issues: see SECURITY.md.
Before you start
For anything bigger than a small fix, open an issue (or comment on one) describing the problem and
how you plan to solve it. Large features start as a short spec in specs/: a spec.md
(why, what, what is out of scope) and a plan.md. specs/component-props
shows the shape. A spec agreed up front saves a rewrite later.
Set up
You need Rust 1.95 or newer (rust-version in Cargo.toml) and the platform libraries listed in
the README's Build from source.
git clone https://github.com/nxtime/papercraft
cd papercraft
cargo build --release
Run a test copy next to your own PaperCraft so it cannot touch your real projects or collide with the running app's MCP port:
PAPERCRAFT_HOME=/tmp/pc PAPERCRAFT_MCP_PORT=29998 ./target/release/papercraft
PAPERCRAFT_HOME moves the project root and the config folder; PAPERCRAFT_MCP_PORT moves the
MCP server. Always set both when developing.
The code depends on craft-ui, which Cargo
fetches from a public git repository at the revision pinned in Cargo.toml.
Make the change
- Fork the repository if needed and make a short-lived branch from current
main(fix/short-name,feat/short-name). Open a pull request intomainwhen ready, or a draft while work is in progress. - Write the test first. Fix a bug by adding a test that fails, then make it pass. See Tests.
- Keep the change focused. One concern per pull request; unrelated cleanups go in their own.
- Run the checks below and fix what they report.
- Update the docs the change touches: the README,
docs/, the tool description for an MCP tool, the skills if agents should now behave differently. - Add a short entry to PROGRESS.md for user-visible changes.
Checks
cargo fmt --all
cargo clippy --all-targets
cargo test --test <target> # the targets your change touches
cargo check --lib --target wasm32-unknown-unknown # the web build
Each file in tests/ is its own binary linking the whole app, so the full suite is slow and heavy
on a desktop. GitHub runs the full Windows suite, the web check and Windows, macOS and Linux
release builds on pull requests and main, and again before each release. The Windows suite can
also be run on demand with gh workflow run test.yml -f ref=<branch>.
Keep the tree free of the third-party branding patterns listed in .debrand.
Tests
- Unit tests sit next to the code in
#[cfg(test)]modules. - Scenario tests live in tests/. They drive the editor with synthetic pointer and
keyboard events;
tests/mcp.rscovers every MCP tool on a headless session. - Aim for 80% coverage on code you add or change, including the error paths.
- GPU-dependent tests skip when no adapter exists. Set
PAPERCRAFT_REQUIRE_GPU=1to make them fail instead. tests/update.rscannot run on Windows (it needs elevation); that failure is known and not yours.- For UI work, run the app, look at it, and attach a screenshot. Headless rendering needs no
display:
papercraft --screenshot ui.png --demo --size 1440x900 --scale 2.
Commits
Conventional commits: type(scope): summary, with the
types feat, fix, refactor, docs, test, chore, perf and ci.
fix(ui): keep the review row's revert button off the hover edge
feat(mcp): add set_screens
docs(readme): add the demo video
Write the summary in the imperative, under about 72 characters, and use the body to say why.
Reference the issue (Fixes #123).
Pull requests
- Fill in the template: what changed, why, how you tested it, screenshots for UI changes.
- Keep it reviewable. If it grows past a few hundred lines of non-generated code, split it.
- The branch must be up to date with
main; rebase rather than merge. - All required checks must pass before merging. Request review when another maintainer is available; a solo maintainer may review and merge their own change after checks pass.
- Expect review comments; they are about the code, not you. Push fixes as new commits and we squash on merge.
Releases
Maintainers cut releases from green main. Merge a version-bump pull request first, then tag its
commit. A v* tag pushed to GitHub builds Windows, macOS and Linux and publishes them after the
tests pass (.github/workflows/release.yml). Do not move a published tag; release a new patch
version for a fix. Contributors do not need to bump versions for ordinary changes.
Licensing
PaperCraft is dual-licensed under MIT or Apache-2.0. Unless you state otherwise, anything you submit is licensed under the same terms, with no extra conditions. Only submit work you wrote or have the right to submit. Code ported from another project needs a compatible license and an entry in THIRD_PARTY.md; bundled assets go in ATTRIBUTION.md.