Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
73 lines (46 loc) · 4.25 KB

CONTRIBUTING.md

File metadata and controls

73 lines (46 loc) · 4.25 KB
Raw

Contributing to Threadwire

Threadwire is in early implementation — the design doc is the source of truth for architecture decisions, and most of the surface area described there doesn't exist as code yet. Check the roadmap before assuming a milestone is further along than it is.

Most valuable contribution right now

Feedback on the design doc — open a Design feedback issue if something looks wrong, underspecified, or worth challenging. This matters more than code right now, since the architecture is the foundation everything else builds on.

Reporting bugs / requesting features

Use the Bug report or Feature request issue templates. For anything security-sensitive, see SECURITY.md instead of opening a public issue.

Branching model

  • dev is the default branch and where all day-to-day work lands. Branch off dev, and open feature/fix/docs/chore PRs back into dev.
  • main only ever moves via a release PR from dev — merging into main is what (once CI/CD exists) triggers artifact/version publishing for the Android and iOS libraries. Don't target main directly with a feature branch.
  • Both dev and main are protected on GitHub: no direct pushes (PRs only, enforced for admins too), no force-pushes, no branch deletion.

Branch naming

Prefix branches with the Conventional Commits type they represent:

Prefix Use for
feat/ New functionality
fix/ Bug fixes
docs/ Documentation only
chore/ Tooling, dependencies, repo maintenance
refactor/ Code change that neither fixes a bug nor adds a feature
test/ Adding or correcting tests
build/ Build system or module structure changes
ci/ CI/CD pipeline changes

Example: feat/sse-transport, fix/reconnect-backoff.

Commit messages

Follow Conventional Commits: <type>(<scope>): <description>.

Examples:

  • feat(core): add Last-Event-ID reconnection to SseChatTransport
  • fix(ui-ios): correct safe-area inset in ChatViewController wrapper
  • docs: add design feedback issue template

Scope is optional but encouraged when the change is localized to one module (core, ui-ios, ui-android, sample-android, sample-ios).

Pull requests

  • One logical change per PR — matches one milestone or a clearly scoped slice of one.
  • Fill in the PR template completely, including the non-negotiable-principles checklist (design doc §2).
  • :sample-app-* must only consume published artifacts, never get privileged access to :core/:ui-* — a PR that breaks this isolation will be asked to change, regardless of what it's trying to demonstrate.

There are two PR templates in .github/PULL_REQUEST_TEMPLATE/:

  • feature.md — default for anything targeting dev (feature/fix/docs/chore/etc.). GitHub should offer a template chooser when opening the PR; if it doesn't show up, open the PR with ?template=feature.md appended to the compare URL.
  • release.md — only for the dev → main release PR. Open it with ?template=release.md appended to the compare URL (.../compare/main...dev?template=release.md&quick_pull=1).

Merge method

  • Feature/fix/docs/chore PRs into dev: squash merge — keep one clean, Conventional-Commits-titled commit per PR.
  • The dev → main release PR: merge commit (not squash) — main should retain the individual feature commits from dev, not collapse a whole release into one commit.

Branch cleanup after merge

The repo has "automatically delete head branches" enabled, so a feature/fix/docs/chore branch is deleted automatically the moment its PR merges into dev — no manual step needed. After pulling dev locally, delete your own local copy of the merged branch too (git branch -d <branch>); git fetch --prune clears the stale remote-tracking ref.

Code of conduct

This project follows the Contributor Covenant.

For AI agents / assistants

See AGENTS.md for a condensed project context designed to be read quickly by an AI coding assistant.