Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
80 lines (51 loc) · 3.44 KB

CONTRIBUTING.md

File metadata and controls

80 lines (51 loc) · 3.44 KB

Contributing to GridSync

Thanks for your interest. GridSync is in active development through v1.0.0; the architecture is in flux. Please read this whole file before opening a non-trivial PR.

Pre-1.0 expectations

  • Issues are welcome — bug reports, feature requests, and questions.
  • For non-trivial PRs, open an issue first to discuss approach. Architectural decisions (especially around multi-ISO support) are tracked in docs/multi-iso-plan.md.
  • Small, focused PRs are preferred over large refactors. PRs that bundle unrelated changes will be asked to split.
  • The schema, public API, and CLI flags may break between minor versions until v1.0.0.

Development setup

GridSync uses mise for tool versions and task running. The .env file is loaded automatically.

cp .env.example .env
# fill in DATABASE_URL, DATA_DIR, etc.

mise install              # install Rust stable
mise run install          # install sqlx-cli + cargo-watch
mise run db:migrate       # apply migrations
mise run build            # verify everything compiles

See README.md for what each variable does.

Branching (gitflow)

  • Branch from develop for features and fixes. Use a descriptive branch name (feature/<short-desc> or fix/<short-desc>).
  • release/vX.Y.Z and hotfix/vX.Y.Z branches target master. See .github/VERSIONING and the Release Checklist section of the PR template.
  • Don't commit directly to master or develop. Branch policy is enforced by .github/workflows/branch-policy.yml.

Before opening a PR

Run all of these locally — CI will run them again:

mise run fmt              # cargo fmt --all
mise run check            # cargo check + clippy -D warnings
mise run test             # cargo test --workspace

If you changed any sqlx::query! or sqlx::query_as! calls, regenerate the offline cache so CI can build without a live database:

mise run db:prepare       # writes .sqlx/ directory

Commit the resulting .sqlx/ directory in the same PR.

Migrations

  • New migrations go in db/migrations/ with the next available NNNN_short_description.sql number.
  • Migrations are embedded in the binaries (sqlx::migrate!) and run on startup, so the schema is always current for a given binary.
  • For schema changes that interact with multi-ISO design, check docs/multi-iso-plan.md before adding columns or tables — there are open ADRs (issues #52, #53) that may affect placement.

Commit messages

Conventional commits are encouraged but not enforced. Keep the subject line under ~70 chars and explain the why in the body when it's not obvious from the diff.

The squash-merge subject from a PR title becomes the commit message on develop, so PR titles should read like good commit subjects.

Code style

  • Run mise run fmt — rustfmt defaults, no project overrides.
  • Clippy must pass with -D warnings (see mise run check).
  • Prefer adding a focused test alongside the change; see issue #11 for the broader test-coverage push.

Reporting security issues

Do not open public issues for vulnerabilities. See SECURITY.md for private reporting channels.

Code of Conduct

By participating, you agree to abide by the Code of Conduct.

License

By contributing, you agree that your contributions will be licensed under the project's AGPL-3.0 license.