Contributing to Neemias

Thanks for contributing to Neemias.

This repository is documentation-first, with the live frontend app under app/ and the backend under workers/. Contributors should treat the specification set as the source of truth before introducing implementation changes.

Source of Truth

Start from these documents:

• README.md
• PRD
• SRS
• SDD
• MTP
• Data Dictionary
• UI Wireframes
• RTM

Contribution Principles

• Keep the app backend-primary with offline resilience.
• Preserve modular boundaries: Attendance, Students, Reports, Sync, Auth, Localization, Shared UI.
• Keep Brazilian Portuguese as default locale.
• Treat WCAG AA and LGPD constraints as baseline, not optional.
• Preserve immutable audit history for student and attendance actions.
• Enforce admin precedence in conflicts.
• Require deletion justification for student removal and retain historical records.

Workflow

1. Open an issue or select an existing issue.
2. Confirm scope against PRD, SRS, and SDD.
3. Create a branch from main.
4. Make focused changes with requirement references.
5. Update docs and test mapping when behavior changes.
6. Open a pull request with checklist completion.

Developer commands:

• pnpm dev:app
• pnpm dev:worker
• pnpm build
• pnpm test

Before committing, the pre-commit hook runs all quality gates automatically. See Quality Gates for the full list of checks.

Git Rules

🚫 Force push is strictly prohibited

Never use git push --force or git push --force-with-lease on any branch shared with others, including main, release branches, and open PR branches.

This includes:

• Overwriting tags (git tag + git push --force origin <tag>)
• Rewriting commit history with git commit --amend or git rebase after push
• Deleting and recreating tags remotely

Why: Force push destroys the shared history that others may have based work on. It can silently delete commits, break CI/CD pipelines, and corrupt release tags. GitHub branch protection rules enforce this, but the rule must be followed in principle — not just as a gate.

What to do instead:

• Need to fix a commit? Add a new commit on top (fix: ...).
• Need to update a PR? Push new commits — don't rebase after review starts.
• Made a mistake on a tag? Create a new tag with the next patch version. Never overwrite an existing tag.

This rule is enforced via GitHub branch protection rules on main. Violations will be treated as a process incident.

Branch Naming

Use one of the following patterns:

• feat/<short-topic>
• fix/<short-topic>
• docs/<short-topic>
• chore/<short-topic>

Examples:

• feat/offline-sync-queue
• docs/adr-template

Commit Message Guidance

Use conventional-style prefixes where practical:

• feat:
• fix:
• docs:
• test:
• refactor:
• chore:

Example:

• feat: add sync queue retry state transitions

Pull Request Checklist

Each pull request should confirm:

• Scope is linked to requirement IDs (for example FR-015, SR-003).
• No conflicts with PRD, SRS, and SDD constraints.
• Role and auth gates are preserved.
• Offline behavior is preserved and no silent data loss is introduced.
• Accessibility impacts are considered (WCAG AA).
• LGPD and data minimization impacts are considered.
• Relevant docs are updated.
• RTM mapping is updated if requirements or tests changed.

Definition of Done

A change is done when:

• Behavior is specified and traceable to requirements.
• Risks are documented (security, accessibility, sync, data integrity).
• Test evidence is provided for changed behavior.
• Documentation and traceability are updated in the same PR.

Security Reporting

Do not open public issues for suspected vulnerabilities.

Follow security-policy.md for private reporting instructions.