Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
193 lines (156 loc) · 9.82 KB

CONTRIBUTING.md

File metadata and controls

193 lines (156 loc) · 9.82 KB
Raw

Contributing To Workstream

Workstream welcomes contributions from humans and agents. Repository access is governed by GitHub permissions and branch protection. The engineering loop exists to make work understandable and reviewable; it is not a separate authorization system.

Workstream itself is source-agnostic governed contribution infrastructure. Flow Identity is its current v0.1 external authentication provider, not its product owner or repository contribution authority. Read the complete product boundary in README.md before changing product terminology or architecture.

By submitting a contribution, you agree that it is licensed under Workstream's AGPL-3.0-only license. Preserve applicable notices when adapting or incorporating third-party material.

Simple Engineering Loop

Intent -> Plan -> Bounded Change -> Tests -> Review -> Pull Request -> Human Merge

Set Up The Development Environment

Use the Developer Setup guide before running repository checks. Docker is the supported cross-host path for macOS and Windows and selects native Linux x86_64 or aarch64 inside the Docker VM. Native host setup is supported only on the Linux/glibc/Python matrix documented there.

Repository engineering checks use a separate, hash-pinned tooling environment, not the backend environment. The tested local tooling setup is Linux x86_64, CPython 3.12, Git, and uv (see the native quickstart for uv installation). From the repository root, install it with:

uv venv .venv --python cpython3.12
uv pip install --python .venv/bin/python --require-hashes --only-binary=:all: \
  -r .github/requirements/agent-gates.txt

The root .venv/ is ignored and separate from backend/.venv/. If you already use that path for another environment, choose another unused path and use its Python consistently below.

On other hosts, use the required Agent Gates check in GitHub Actions. The backend Docker service mounts only backend/; it is not a repository-root tooling environment. Do not change dependency hashes to force a host install.

For an editorial correction to README or ordinary documentation outside process-control paths, record intent and scope in the pull request. A meaningful standalone change uses .commitrail/changes/<lowercase-kebab-slug>.md, based on .commitrail/CHANGE_TEMPLATE.md, declaring exactly one live Initiative: None, without an initiative overview or index row. Work in an existing initiative keeps its initiative record; multi-PR work also uses one concise overview. The Commitrail contribution paths list the exact paths that require a record even for a small correction. Substantive specification or behavior changes need a record regardless of path; the path check cannot determine semantic risk. Commitrail records explain work; GitHub permissions and branch protection govern contribution authority.

Find The Current Contract

Before implementation, update from current main and read:

  1. README.md for the product boundary and current v0.1 summary.
  2. v0.1 Roadmap And Capability Status for implemented, hidden, in-progress, and remaining capabilities.
  3. Commitrail Engineering Index for durable initiative dispositions and remaining boundaries. Inspect GitHub separately for the live pull-request view of transient work.
  4. Architecture Lockdown, accepted ADRs, and the canonical specification for the subsystem being changed.

Code, migrations, tests, accepted ADRs, and canonical repository specifications define implemented or required behavior. Open pull requests describe work in progress. Calendar plans, early chunk specifications, imported files under docs/reference_specs/, internal review records, and closed initiative records are useful history unless a current document explicitly adopts them; they are not by themselves current sequencing or proof that behavior is live.

The active migration graph is the clean v0.1 baseline. A local database with a removed pre-v0.1 revision must be recreated; do not add a compatibility stamp, bridge migration, or second baseline.

Roadmaps and status documents must use capability milestones and evidence. Do not introduce delivery promises such as day plans, numbered weeks, or rolling time windows as repository authority.

Contributors with GitHub write access may create a branch, implement a bounded change, and open a pull request. Contributors without write access may use a fork and open a normal pull request.

Before claiming a remaining boundary, inspect open pull requests and coordinate any overlapping path or behavior ownership. Static status files do not attempt to mirror transient branches because that information becomes stale at merge. Review logs are evidence for earlier exact changes, never an active queue or approval gate.

Before Opening A Pull Request

  • Explain the goal, scope, non-goals, and important design decisions.
  • Keep the change small enough to review.
  • Run the relevant behavior tests, lint and type checks; full hosted suites and real API drills remain required. Coverage is diagnostic, not a merge threshold.
  • Preserve security defaults and meaningful negative-path proof. Do not add tests to meet a percentage or count. For test removals/consolidations, name the retained behavioral proof or the retired requirement. Keep real database, transaction, concurrency and storage checks where those boundaries matter.
  • Record important reviewer findings and how they were resolved.
  • Reconcile with current main and rerun affected checks.
  • Before marking the PR ready, assess its impact on docs/roadmap_status.md. Update affected capability, exposure, completed/remaining work, and next-dependency sections in this same PR to reflect its intended merged outcome, including relevant changes from main. If there is no impact, explain why in the PR instead of making a no-op edit. Do not defer this to a separate post-merge roadmap PR. Reconcile affected summaries, scoreboard rows, dependency diagrams, release gates and current initiative navigation—not only the newest detail paragraph. Distinguish implemented, publicly exposed and deployed behavior, preserve policy branches, and link detailed evidence instead of repeating its history. This adds no separate gate, status file or post-merge step.
  • In the change record, declare the intended merge outcome and durable disposition (Planned, Complete, Stopped, or Superseded). Update an initiative overview or index row only when its durable meaning changes. Never commit transient review or CI state, and never create a second post-merge memory PR.

Commit/freeze the candidate. With the local tooling setup above, run the same atomic check before pushing; other hosts inspect the required hosted result. Its base-to-HEAD comparison does not validate uncommitted edits:

.venv/bin/python scripts/check_commitrail_records.py --base-ref origin/main

Security, authorization, payments, workflow, architecture, and other high-risk changes require focused internal review before they are ready to merge. Small low-risk changes use proportionate review. Reviews are evidence, not permission to contribute.

Review And Merge

GitHub CI validates repository quality. CodeRabbit and internal agents supplement human review. A maintainer must explicitly approve the final pull request before it is merged, and the user must explicitly approve that specific pull request for merge. A new push invalidates affected internal evidence and stale GitHub approval. Branch protection requires an eligible human other than the latest pusher to approve the most recent reviewable push, and requires all review conversations to be resolved before merge.

Different initiatives may proceed concurrently in separate branches or worktrees. If another pull request changes the base, inspect the new delta and rerun affected checks; unchanged evidence does not need ceremonial repetition.

For Backend failure diagnosis and safe partial reruns, follow the canonical Backend testing operations guide.

Behavior Ownership Catalogue

The hosted behavior-mutation check is temporarily retired because its callable-wide survivor policy blocked declaration-only changes by mutating unchanged executable lines. Do not treat a historical behavior claim or a catalogue candidate as a required PR gate.

The versioned catalogue foundation lives under .ci/behavior-ownership/. Contributors can run its read-only inventory, candidate generator, and validator from backend/:

.venv/bin/python -m scripts.behavior_ownership inventory
.venv/bin/python -m scripts.behavior_ownership generate
.venv/bin/python -m scripts.behavior_ownership validate

Candidate output is discovery assistance only. It cannot become reviewed ownership without an explicit catalogue record and the required human and internal review. The validator reports unresolved targets while population is in progress; that report does not block ordinary contributions.

Existing claim, schema, policy, dependency, and evidence files remain as historical design input. They do not replace focused tests, hosted Backend lanes, real integration proof, internal review, CodeRabbit, or human merge approval. Behavior-mutation enforcement must not resume until a fresh changed-line-aware plan is approved and proves that unchanged executable lines cannot block a declaration-only change.

Durable Records

Keep only Commitrail records that materially explain intent, boundaries, decisions, evidence, or remaining risks. Git history preserves retired detail. Git and GitHub are authoritative for commits, reviews, checks, approvals, and merges.