Files
papercraft/CONTRIBUTING.md
Marcos Paulo 15cba71bf0 ci: gate pull requests and reuse release caches (#2)
* ci: gate pull requests and share release caches

* fix(ci): keep release caches restore only
2026-10-29 20:13:28 -03:00

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 todo or partial are 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

  1. Fork the repository if needed and make a short-lived branch from current main (fix/short-name, feat/short-name). Open a pull request into main when ready, or a draft while work is in progress.
  2. Write the test first. Fix a bug by adding a test that fails, then make it pass. See Tests.
  3. Keep the change focused. One concern per pull request; unrelated cleanups go in their own.
  4. Run the checks below and fix what they report.
  5. Update the docs the change touches: the README, docs/, the tool description for an MCP tool, the skills if agents should now behave differently.
  6. 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.rs covers 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=1 to make them fail instead.
  • tests/update.rs cannot 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.