# Contributing to CertVault

Thank you for helping improve CertVault. Bug reports, documentation, tests, and focused code changes are welcome.

## Before you start

- Search existing issues and pull requests before opening a duplicate.
- Use the bug-report form for reproducible defects and the feature-request form for proposed behavior.
- Open an issue before beginning a large change so its design and scope can be discussed.
- Never include credentials, tokens, certificate private keys, real private domains, database files, or other sensitive homelab information in an issue, screenshot, fixture, or commit.
- Report suspected vulnerabilities privately according to [SECURITY.md](SECURITY.md).

## Development setup

Requirements:

- Go at the version declared by `backend/go.mod`
- Node.js 26 with pnpm 11.24.0
- OpenSSL for generation of local development secrets
- Docker for container builds and the canonical browser test environment

Install dependencies and start the mock ACME development environment:

```sh
make dependencies
make dev
```

Open `http://localhost:8081` and authenticate with `certvault-dev-admin`. Development state is written under the ignored `.cache/dev` directory. Mock ACME mode issues locally signed certificates without contacting a certificate authority or DNS provider.

## Project structure

- `backend/` contains the Go API, authentication, ACME services, persistence, and encrypted certificate storage.
- `web/src/` contains the React console, organized into pages, reusable components, and dialogs.
- `config/` contains complete example and development YAML configurations.
- `docs/openapi.yaml` describes the machine-facing API.
- `web/client/` contains the installer template and runtime scripts. The web build generates `web/public/client/` for installation and signed updates.

Keep HTTP handlers thin, put ACME and certificate behavior in services, and isolate database access in the model-specific repositories. Reusable UI behavior belongs in components or dialogs rather than individual pages.

## Required checks

Run the full validation suite before opening a pull request:

```sh
make check
```

This verifies Go, frontend, and shell formatting, runs `go vet`, golangci-lint, ESLint, backend and frontend tests, type-checks the UI, and builds both production layers. Use `make format` and the relevant lint-fix command before manually correcting formatting issues.

`make format-shell` formats `web/client/*.sh` and `web/scripts/*.sh` with shfmt using two-space indentation and POSIX shell syntax. `make format-check-shell` checks the same files without changing them. These commands install the pinned formatter into `.bin/` automatically; generated client assets are excluded.

New behavior should include tests at the closest useful layer. Security-sensitive behavior must be enforced by the backend even when the UI also prevents an invalid action.

For visible UI changes, run the browser integration and visual regression suite:

```sh
make test-e2e-docker
```

Review intentional baseline changes using the workflow in
[e2e/README.md](e2e/README.md). CI uploads browser reports, traces,
and screenshot differences. `make screenshots` and `make screenshots-docker`
regenerate the same root images used by documentation and visual regression.

## Pull requests

- Keep changes focused and avoid unrelated refactoring or formatting.
- Explain the problem, chosen solution, and meaningful tradeoffs.
- Call out changes to configuration, persistence, API compatibility, authentication, authorization, cryptography, secret handling, or hooks.
- Update examples, API documentation, and tests when behavior changes.
- Use reserved example domains such as `example.com`; never use private or personally operated domains in fixtures.
- Keep the branch current with `master` and ensure CI passes.

## Licensing

By submitting a contribution, you agree to license it under the [GNU Affero General Public License v3.0](LICENSE), the same license that applies to CertVault.

## Commits

Use concise imperative commit subjects, such as `Prevent deletion of current ACME account`. Release notes are generated from commit messages, so user-facing commits should describe the observable change clearly.