Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
249 lines (200 loc) · 9.88 KB

CONTRIBUTING.md

File metadata and controls

249 lines (200 loc) · 9.88 KB
Raw

Contributing to Squarewise

Thank you for your interest in contributing to Squarewise! We welcome contributions from the community. Squarewise is a documentation-first, tracker-driven, modular Kotlin/Spring application. To ensure high code quality, clean architecture, and maintainable operations, all contributors follow the guidelines outlined below.

Table of Contents

Code of Conduct

Participation in Squarewise is governed by the Contributor Covenant Code of Conduct. Read it before contributing. Report conduct incidents through its private enforcement channel rather than in a public issue.

How to Contribute

Reporting Bugs & Security Issues

Suggesting Enhancements

Before building a major new capability or changing service boundaries:

  1. Review docs/product/mvp.md and docs/architecture/.
  2. Use the feature request form to outline its motivation, desired outcome, design trade-offs, and boundary implications.

Working Agreement & Delivery Tracking

Squarewise operates under a strict documentation-first workflow:

  • Live status, assignment, priority, iteration, milestones, and blockers move to mapped GitHub issues and the Squarewise Delivery project after the DOC-28 cutover recorded in docs/tasks/registry.yaml.
  • Migrated task specifications remain under docs/tasks/details/, with deprecated historical IDs and issue mappings in the registry. New work uses its GitHub issue number and issue body instead of allocating a local ID.
  • Verified implementation evidence is logged in docs/tasks/progress.md.
  • The authority boundary and migration rules are documented in docs/tasks/README.md.
  • Read docs/working-agreement.md for full context on our execution protocol.

License and contribution rights

Squarewise first-party work is licensed under the AGPL-3.0-only license. Before submitting a contribution, confirm that you have the right to submit it under that license and preserve any third-party copyright and license notices. Squarewise does not currently use a CLA or DCO; the full scope and exception policy is documented in docs/operations/licensing.md.

Development Setup

Prerequisites

  • JDK 25+: Squarewise uses modern Kotlin and JVM 25 features.
  • Docker & Docker Compose v2: For PostgreSQL 17, RabbitMQ 4.3, and Mailpit.
  • Python 3.11+: Used for contract and schema validation tools.
  • Gradle: Provided via ./gradlew wrapper (no separate installation required).

Verify your environment using our self-check tool:

make doctor

Setting Up Your Local Environment

  1. Clone the repository:

    git clone https://github.com/ohbus/squarewise.git
cd squarewise

  2. Verify prerequisites and build toolchain:

    make bootstrap

  3. Start local infrastructure (choose one approach):

    • Background dependencies only (Postgres, RabbitMQ, Mailpit) when running apps natively via IDE/Gradle: 
      make deps-up
    • Full containerized stack (all 4 apps + dependencies): 
      make full-up

Development Workflow

1. Branching Strategy

  • Always branch off master.
  • Use descriptive branch names with clear prefixes:
    • feat/<feature-name> for new features
    • fix/<bug-fix-name> for bug fixes
    • refactor/<refactor-scope> for refactoring
    • docs/<doc-update> for documentation updates
git checkout master
git pull origin master
git checkout -b feat/my-new-feature

2. Pre-Implementation Planning

Before writing code:

  • Check existing technical libraries (libs/ids, libs/errors, libs/db, etc.) to maximize code reuse.
  • Ensure any API modifications match contracts in contracts/.
  • Review relevant architecture specifications in docs/architecture/.

3. Implementing Code

  • Keep code cognitively light and easy to read.
  • Write minimal, modular, cohesive code.
  • Avoid introducing speculative abstractions (YAGNI).
  • Strictly adhere to the Design Principles.

4. Testing & Validation

All changes must be thoroughly validated before committing:

# Run fast unit tests
make test-unit

# Run full test suite with code coverage reports
make coverage

# Validate OpenAPI, GraphQL, and JSON schemas
make contracts

# Run linting (Spotless & Gradle checks)
make lint

# Validate full suite (contracts, tests, coverage, jar packaging)
make check

If the development stack is running, you can also run the live multi-service acceptance tests:

make acceptance-live

5. Committing Changes

  • Write concise, descriptive commit messages following the Conventional Commits specification:
    • feat(...): new functionality
    • fix(...): bug fix
    • refactor(...): refactoring without functional changes
    • test(...): adding or modifying tests
    • docs(...): documentation changes
  • Never commit .env files, credentials, build artifacts, or IDE-specific project files.
  • Ensure git diff --check produces no trailing whitespace or formatting warnings.
git add <files>
git commit -m "feat(expense-core): implement recurring expense calculator"

6. Submitting a Pull Request

  1. Push your branch to GitHub: 
    git push origin feat/my-new-feature
  2. Open a Pull Request targeting master.
  3. Complete the automatically loaded PR template with:
    • Objective: What problem does this PR solve?
    • Changes: Bulleted summary of changes made.
    • Verification: Exact test/validation commands executed and their output.
    • Documentation: Confirmation of updated docs/KDocs.
  4. Ensure all CI checks pass.

Pull requests must not contain undisclosed vulnerability details. Send security questions and reports to security@subhrodip.com under the Security Policy.

Architecture & Design Principles

All contributions must follow docs/quality/programming-principles.md and docs/quality/coding-guidelines.md.

SOLID File Separation

In enterprise code, each class or interface must reside in its own dedicated source file:

  • Never combine JPA @Entity definitions, Spring Data @Repository interfaces, and business @Service or store adapter implementations in a single file.
  • Follow enterprise packaging (entities/, repositories/, services/, etc.).

API Endpoints & Contracts

  • Centralized API Constants: Hardcoded URL strings and standard headers (X-Request-Id, Idempotency-Key) are prohibited in controllers, gateways, and tests. Always reference com.subhrodip.squarewise.ids.ApiEndpoints (e.g. ApiEndpoints.ExpenseCore.V1.PATH_GROUPS).
  • Contracts First: Any change to REST or GraphQL contracts must be reflected in contracts/ and verified with make contracts.

KDoc Documentation Requirement

  • Ensure all public classes, interfaces, methods, models, and endpoints include structured KDoc comments (/** ... */) detailing intent, parameters, return values, invariants, and failure modes.

Helpful Commands Cheat Sheet

Task Command
View all available commands make help
Check environment tools make doctor
Start backing services make deps-up
Stop backing services make deps-down
Start complete container stack make full-up
Stop complete container stack make full-down
Validate OpenAPI & GraphQL schemas make contracts
Run fast unit tests make test-unit
Run all tests with JaCoCo coverage make coverage
Run linting & formatting checks make lint
Comprehensive check (CI mirror) make check
Run live multi-service acceptance test make acceptance-live