Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
84 lines (62 loc) · 2.95 KB

CONTRIBUTING.md

File metadata and controls

84 lines (62 loc) · 2.95 KB

Contributing

Join thecartine Discord

Release process

Knots uses Changesets to manage release metadata.

  1. Add a changeset for user-facing changes.
  2. Merge to main.
  3. Changesets workflow opens/updates a Version Packages PR.
  4. Merge version PR.
  5. Release workflow builds binaries, creates release assets, and publishes tag v<version>.

Published assets:

  • knots-v<semver>-darwin-arm64.tar.gz
  • knots-v<semver>-linux-x86_64.tar.gz
  • knots-v<semver>-linux-aarch64.tar.gz
  • knots-v<semver>-checksums.txt

Local release/install smoke test

Run the installer smoke script before publishing major release process changes:

scripts/release/smoke-install.sh

The script validates both latest and pinned install flows and confirms kno.previous is retained after reinstall. It also verifies the installed binary exactly matches the local cargo build --release output (version + SHA-256 hash).

Optional smoke test env vars:

  • KNOTS_SMOKE_INSTALL_DIR=/absolute/path keeps the installed binary at a persistent location.
  • KNOTS_SMOKE_KEEP_TMP=1 retains temporary tarball/server artifacts after the run.

Toggle between release and local test binaries

Use channel scripts to keep both binaries installed and switch with a symlink:

# Install GitHub release binary into ~/.local/bin/acartine_knots/release/kno
scripts/release/channel-install.sh release

# Install local smoke-tested build into ~/.local/bin/acartine_knots/local/kno
scripts/release/channel-install.sh local

# Switch active ~/.local/bin/kno symlink
scripts/release/channel-use.sh release
scripts/release/channel-use.sh local

# Show current active target
scripts/release/channel-use.sh show

You can override defaults with:

  • KNOTS_CHANNEL_ROOT (default: ~/.local/bin/acartine_knots)
  • KNOTS_ACTIVE_LINK (default: ~/.local/bin/kno)
  • KNOTS_LEGACY_LINK (default: ~/.local/bin/knots)

Knots remains supported as a compatibility alias:

knots --version

Workflow metadata contract

Knots exposes workflow routing metadata for downstream consumers. When you change workflow/profile definitions or knot-view serialization, keep these surfaces aligned:

  • step_metadata and next_step_metadata on knot JSON responses such as kno show --json and kno ls --json
  • step_owner, next_owner, step_artifact, and review hint fields in CLI show output
  • step_metadata and next_step_metadata in persisted .knots/index/.../idx.knot_head.json events

The metadata contract is:

  • owner.kind identifies the responsible actor for the current or next action
  • output.artifact_type and output.access_hint describe the expected artifact
  • review_hint tells reviewers what to inspect on review-oriented steps

Any change to these fields should include documentation updates and response- level tests that cover at least three workflow patterns.