Contributing

Eagraí Clainne is a self-hosted family organizer with a single maintainer. You are welcome to report a problem or send a change. This page is the short version. The full contributing guide lives in the repository.

Get access

The project lives on a self-hosted Forgejo instance at git.eagraiclainne.ie. Issues and pull requests both need an account there.

  1. Register at https://git.eagraiclainne.ie and verify your email address.
  2. Turn on two-factor authentication. The host blocks accounts that skip this step.
  3. Fork the eagraiclainne/app repository.

Set up

The project uses devbox for a reproducible toolchain. Two commands cover the everyday loop:

# format, vet, lint, test, and i18n checks — run before every push
make check

# full local deploy to a kind cluster, served at localhost:8080
make deploy

Verify a behavior change by hand in the local deploy, not only against the tests.

Make a change

Read the System rules at the top of AGENTS.md first. They are the product invariants — surface parity, the style canon, self-containment, the server invariants, and the quality bar. A change that moves a convention updates AGENTS.md in the same change.

Record an Architecture Decision Record in docs/adr/ for a significant change: authentication or authorization, the database schema, a new API service, or a large refactor.

Commit messages

Commits must follow Conventional Commits. This is not a style preference. The release tool reads the commit history and computes the next version from it:

  • fix: raises the patch version.
  • feat: raises the minor version.
  • A ! after the type, or a BREAKING CHANGE: footer, raises the major version.
  • chore:, ci:, docs:, and the rest cut no release.

The subject line is type(scope): summary. CI rejects a pull request with a commit that does not match this format, so check your history before you push. Write a body that explains why the change exists, not what it does.

Submit

  1. Create a branch on your fork.
  2. Make your change. Run make check until it passes.
  3. Open a pull request against eagraiclainne/app.
  4. Make sure every check is green. A red push does not merge.

The maintainer merges with fast-forward only, so your commits land on main exactly as you wrote them. Keep each commit to one logical change.

Licensing

The project is licensed under AGPL-3.0. When you send a contribution, you agree that it carries the same terms. Inbound matches outbound. There is no separate contributor agreement to sign.