Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
92 lines (71 loc) · 5.08 KB

CONTRIBUTING.md

File metadata and controls

92 lines (71 loc) · 5.08 KB
Raw

Contributing to QuickCrate

QuickCrate is currently a focused Android-first Compose Multiplatform demonstration. Contributions should strengthen the golden path, proof, accessibility, or architecture before adding breadth.

Before starting

  1. Read AGENTS.md, HANDOFF.md, SPEC.md, ARCHITECTURE.md, ROADMAP.md, and TESTING.md.
  2. Check existing repository state and avoid overwriting unrelated changes.
  3. Confirm the task fits the current roadmap or obtain owner approval for a scope/architecture change.
  4. Define acceptance and verification before editing multiple files.

The repository currently has no root application-code license. Until the owner selects one, public visibility does not grant reuse rights; clarify contribution/licensing intent before accepting external contributions.

Development workflow

  • Branch from current main for material work.
  • Keep one bounded purpose per change.
  • Preserve the working vertical slice throughout development.
  • Prefer pure domain changes and shared components over platform duplication.
  • Add no dependency unless the existing stack cannot reasonably satisfy the requirement; record major dependency decisions in DECISIONS.md.
  • Run focused checks while iterating and the required gate from TESTING.md before handoff.
  • Update continuity docs in the same change when behavior, architecture, verification, or priorities shift.

Code placement

  • Android setup/platform implementation: androidApp or shared/src/androidMain.
  • Shared screens and ViewModels: shared/src/commonMain/.../feature.
  • Reusable tokens/components: shared/src/commonMain/.../designsystem.
  • Pure models/rules: shared/src/commonMain/.../domain.
  • API/repository/persistence: shared/src/commonMain/.../data.
  • Routes/back-stack ownership: shared/src/commonMain/.../navigation.
  • Bundled assets/data/fonts: shared/src/commonMain/composeResources.

If a product feature requires Android imports in common feature code, define a platform seam instead of moving the feature into androidApp.

Kotlin and state conventions

  • Use immutable UI state data classes and StateFlow.
  • Use one sealed event type and one onEvent entry per ViewModel.
  • Use buffered/narrow effects only for one-shot completion/navigation/messages.
  • Keep business rules pure and covered by common tests.
  • Use suspend repository writes and Flow-based observed state.
  • Keep route payloads serializable and ID/enum-only.
  • Keep pricing as Long paise through domain, persistence, and snapshots.
  • Name fake/demo behavior explicitly; never make a stub look like a real integration.

UI and accessibility conventions

  • Consume QuickCrateTheme and reusable components; no raw brand colors or replacement button/card/field implementations in features.
  • Keep touch targets at least 48 dp.
  • Add content descriptions, roles, selected/error/state semantics where applicable.
  • Do not make color, animation completion, or remote content necessary to understand/use a screen.
  • Verify light/dark, compact/medium, font scale 1.0/1.3, and animator scale 0 for material UI changes.
  • Use original local artwork only and update stable artwork mappings/offline checks.

Persistence conventions

  • Repository contracts isolate feature code from Room/fake implementations.
  • Schema changes require a Room version bump, migration, generated schema, and round-trip test.
  • Preserve order/address/product snapshots; do not resolve old orders from the live catalog.
  • Checkout failure occurs before mutation. Successful order creation and cart clear remain one transaction.
  • Never reseed by deleting user/demo state; version seed changes explicitly.

Tests required by change

Change Minimum evidence
Domain/service Focused common test + standard gate
Repository/fake Success/failure/idempotency host test + standard gate
Room/schema Round trip/migration + clean gate + connected test
ViewModel State/event/effect test + standard gate
Compose component/screen Semantics/state coverage + visual matrix + connected journey
Navigation Route/back/recreation test + connected journey
Docs/screenshots Link/image check + diff check + standard gate

Commit and review guidance

  • Use concise imperative/conventional messages when appropriate, such as feat:, fix:, test:, docs:, or build:.
  • Do not include build output, local SDK paths, environment files, keys, ad hoc screenshots, or unrelated formatting.
  • Review the staged diff and verification evidence before committing.
  • Do not move release tags or publish external state without explicit owner approval.

Pull request checklist

  • Scope and acceptance are clear.
  • Golden path remains stable.
  • Offline and integer-money invariants remain intact.
  • Tests/checks match the risk and pass.
  • UI changes include accessibility/responsive evidence.
  • Schema/assets/routes include their required companion updates.
  • No secret, runtime URL, remote image, network permission, or generated junk was added.
  • HANDOFF.md, ROADMAP.md, TESTING.md, DECISIONS.md, and CHANGELOG.md were updated where relevant.