Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
137 lines (95 loc) · 5.38 KB

CONTRIBUTING.md

File metadata and controls

137 lines (95 loc) · 5.38 KB
Raw

Contributing to runx

Thanks for considering a contribution. This document covers the contribution workflow and the sign-off required on every commit.

Licensing

runx is licensed under the MIT License, Copyright (c) 2026 nilstate. By contributing, you agree that your contributions will be licensed under the same license. See LICENSE for the full text.

Developer Certificate of Origin (DCO)

All commits to this repository must be signed off under the Developer Certificate of Origin. The DCO is a lightweight affirmation that you have the right to submit the contribution under the project's license. There is no separate CLA to sign.

Sign off on every commit by adding a Signed-off-by: trailer. The easiest way is to pass -s to git commit:

git commit -s -m "your commit message"

This appends a trailer that looks like:

Signed-off-by: Your Name <your.email@example.com>

The name and email must match the real identity you wish to be associated with the contribution. Pseudonymous sign-offs are not accepted.

The full DCO text (reproduced here for reference):

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or

(b) The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or

(c) The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it.

(d) I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project and the open source license(s) involved.

Contribution workflow

  1. Open an issue describing the change before sending a PR for anything non-trivial. Small fixes can go straight to a PR.
  2. Fork the repo and create a topic branch from main.
  3. Make your change. Keep commits focused and conventional (feat:, fix:, docs:, chore:, etc.).
  4. Run the workspace checks locally:
    • pnpm install
    • pnpm build
    • pnpm typecheck
    • pnpm test
  5. Sign off your commits with git commit -s (see DCO above).
  6. Open a pull request against main with a clear description of the change and any test or validation evidence.

Development setup

The native Rust CLI needs Rust 1.85 or newer and stays useful without Node, pnpm, tsx, or TypeScript installed. The workspace and the npm wrapper need Node.js 20 or newer and pnpm 10 or newer.

From the OSS workspace:

cd oss
pnpm install
pnpm build
pnpm test

For a type-only check:

pnpm typecheck

For the fast local loop:

pnpm test:fast

For Rust kernel parity work, run:

pnpm rust:check

This is blocking evidence for Rust-owned kernel and contract surfaces. The command uses cargo-deny and cargo-public-api; if they are missing, install them with:

cargo install cargo-deny cargo-public-api
rustup toolchain install nightly --profile minimal

test:fast uses vitest.fast.config.ts and is intended for package-adjacent iteration. pnpm test remains the full workspace suite and includes the isolated CLI package contract check.

See docs/how-we-test.md for the full test lane split.

To use the local CLI from any directory:

pnpm cli:link-global
runx --help

Re-run pnpm build after source changes that affect compiled package output.

Skill authoring paths

Use runx new <name> when you already have the runx CLI available locally and want a standalone skill package:

runx new docs-demo

Community skills should be authored as standalone packages; the runx repo itself is the first-party lane for official skills, runtime code, tests, and examples.

The first runnable example is documented in docs/getting-started.md. The generated package export index is in docs/api-surface.md.

Releasing

The CLI ships from a single cli-vX.Y.Z tag to every channel (GitHub Release, npm, crates.io, Homebrew, Scoop, winget, AUR, Docker) plus the runx.ai/install one-liner. The tag is the only source of truth; release jobs stamp the version, they are never hand-committed. Full pipeline, versioning model, required secrets, and how to cut a release are in docs/releasing.md.

Code of conduct

This project follows the Code of Conduct. Report conduct concerns privately through GitHub's private report flow on the repository; they are handled in confidence.

Reporting security issues

Do not open a public issue for a vulnerability. Use GitHub's private vulnerability reporting on the repo (Security tab, "Report a vulnerability"). Disclosure is coordinated: a fix is prepared privately, then the issue and fix are disclosed together. Full details are in SECURITY.md.