Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
185 lines (133 loc) · 5.58 KB

CONTRIBUTING.md

File metadata and controls

185 lines (133 loc) · 5.58 KB

Contributing to domus

Thank you for your interest in contributing to domus — a digitalization platform for Catholic parish administration. We welcome contributions from developers of all backgrounds and experience levels.

Table of Contents

Code of Conduct

Be respectful, inclusive, and constructive in all interactions. We are building this project to serve a real community — please treat all contributors and users with dignity.

Getting Started

Prerequisites

  • Node.js >= 20
  • pnpm >= 9
  • PostgreSQL (for local development)

Setup

# Clone the repository
git clone https://github.com/paroki/domus.git
cd domus

# Install dependencies
pnpm install

# Copy environment variables
cp apps/dash/.env.example apps/dash/.env.local

# Run database migrations
pnpm db:migrate

# Start development server
pnpm dev

Project Structure

domus/
├── apps/
│   ├── dash/          # Next.js 15 — main application (pkrbt.id)
│   └── cron/          # Cloudflare Workers — scheduled tasks
├── packages/
│   ├── core/          # Framework-agnostic business logic (Clean Architecture)
│   ├── db/            # Drizzle ORM schema, migrations, repository implementations
│   └── auth/          # Better Auth configuration
├── docs/              # Project documentation
├── TASKS.md           # Development tasks and backlog
└── CONTRIBUTING.md    # This file

For a deeper understanding of the architecture, refer to:

Development Workflow

  1. Fork the repository and create a branch from main.
  2. Branch naming convention: feat/short-description, fix/short-description, chore/short-description.
  3. Make your changes, following the Coding Standards.
  4. Ensure all checks pass locally before pushing.
  5. Open a Pull Request against main.

Commit Convention

domus uses Conventional Commits enforced by Commitlint.

Format

<type>(<scope>): <short description>

Types

Type When to use
feat A new feature
fix A bug fix
chore Maintenance tasks, dependency updates
docs Documentation changes only
refactor Code changes that neither fix a bug nor add a feature
test Adding or updating tests
ci CI/CD configuration changes

Examples

feat(auth): add Google OAuth login flow
fix(attendance): correct GPS radius validation
docs(erd): update org_memberships table fields
chore(deps): upgrade Next.js to 15.2.0

Husky will automatically validate your commit message via Commitlint. Invalid commit messages will be rejected.

Pull Request Guidelines

  • Keep PRs focused — one feature or fix per PR.
  • Include a clear description of what was changed and why.
  • Reference related issues or tasks (e.g., Closes #42, Ref: F2.1).
  • Ensure the CI pipeline passes before requesting a review.
  • Be responsive to review feedback.

Coding Standards

Language

  • All code, comments, and documentation must be written in English.
  • User-facing text within the application uses Bahasa Indonesia.

Naming Conventions

Context Convention Example
Database table names snake_case financial_periods
Database field names camelCase createdAt, organizationId
Entity (Zod schema) PascalCase + Entity suffix ProfileEntity
Inferred type PascalCase Profile, Event
Enum name PascalCase AccountStatus
Enum value PascalCase AccountStatus.Pending
Repository interface PascalCase + I prefix IProfileRepository
Service camelCase + Service suffix profileService
Server Action camelCase + Action suffix updateProfileAction
File name kebab-case profile.service.ts
Folder name kebab-case org-memberships/
Internal package @domus/ + kebab-case @domus/core
Variable & function camelCase getProfile, userId
Global constant SCREAMING_SNAKE_CASE MAX_UPLOAD_SIZE
React component PascalCase ProfileCard

Architecture Rules

  • All business logic belongs in packages/core/service/ — never in the app layer.
  • Services must return Result<T> — never throw exceptions.
  • Server Actions must return ActionResult<T> — never throw exceptions.
  • app/**/*.tsx files (non-route) must be thin exports only — no logic, no wrappers.
  • UI Components: NEVER modify files in apps/dash/src/shared/ui/shadcn/. Direct edits to shadcn base components are prohibited to maintain upgradeability. Perform all customizations by creating wrapper components or extending styles in apps/dash/src/shared/ui/components/.

Linting & Formatting

domus uses Biome for linting and formatting. Run checks locally:

pnpm lint       # Run Biome lint
pnpm format     # Run Biome format

Husky runs these checks automatically on pre-commit.

License

By contributing to domus, you agree that your contributions will be licensed under the MIT License.