# Contributing to MiauInv

Thank you for considering a contribution to MiauInv.

MiauInv is a self-hosted/private inventory management system. Contributions are accepted through pull requests only. Direct pushes to the `main` branch are not allowed.

## Contribution Model

All changes must be submitted through pull requests.

This applies to:

- new features,
- bug fixes,
- refactoring,
- documentation updates,
- CI/CD changes,
- security improvements,
- release preparation work.

Contributors should work from a fork of the repository. Changes should be developed in a dedicated branch in the fork and then submitted as a pull request to the upstream repository.

Code snippets, patches, or implementation ideas are only accepted into the project if they are submitted through a pull request.

## Protected Main Branch

The `main` branch is protected.

The following rules apply:

- nobody may push directly to `main`,
- all changes must go through pull requests,
- pull requests must target `main` unless a maintainer explicitly requests a different target,
- every commit in a pull request must be signed,
- unsigned commits will not be accepted.

## Signed Commits

All commits must be signed.

This is mandatory for:

- commits on feature branches,
- commits on bugfix branches,
- commits on chore/refactoring branches,
- commits in pull requests,
- release preparation commits.

Pull requests containing unsigned commits must be fixed before they can be merged.

Example:

```bash
git commit -S -m "feat(auth): add account recovery flow"
```

To check whether commits are signed:

```bash
git log --show-signature
```

If a commit was created without a signature, rewrite or recreate it before opening the pull request.

## Branch Naming

Branches should use lowercase, hyphen-separated descriptions and include the related issue ID where possible.

Recommended format:

```text
<type>/<issue-id>-<lowercase-description>
```

Examples:

```text
feature/5-mfa-support
bugfix/12-fix-refresh-token-rotation
chore/18-update-ci-workflow
docs/21-update-authentication-docs
refactor/24-clean-up-storage-layer
```

Common branch types:

| Type | Usage |
| --- | --- |
| `feature` | New functionality. |
| `bugfix` | Bug fixes. |
| `chore` | Maintenance work, tooling, dependency updates, CI changes. |
| `docs` | Documentation-only changes. |
| `refactor` | Code restructuring without functional behavior changes. |
| `release` | Release preparation branches. |

## Feature and Bugfix Workflow

When working on a feature, bugfix, or other change:

1. Create or choose the related issue.
2. Fork the repository.
3. Create a branch in your fork using the branch naming scheme.
4. Implement the change.
5. Keep commits signed.
6. Push the branch to your fork.
7. Open a pull request against the upstream `main` branch.
8. Use the pull request template.
9. Ensure the pull request describes the change and links the issue.

When a feature, bugfix, or chore branch is complete, a pull request may be created from that branch into `main`.

## Pull Requests

Pull requests must:

- use the repository pull request template,
- describe the change clearly,
- link the related issue where applicable,
- contain signed commits only,
- avoid unrelated changes,
- keep documentation updated when behavior changes,
- keep the implementation consistent with the existing code structure.

Pull requests should be focused. A pull request should usually address one feature, one bug, or one maintenance task.

If a pull request changes authentication, authorization, account security, database schema, or deployment behavior, the relevant documentation should be updated in the same pull request.

## Issues

Issues should use the available issue templates whenever possible.

A good issue should include:

- a clear description,
- expected behavior,
- actual behavior, if reporting a bug,
- reproduction steps, if applicable,
- relevant logs, screenshots, or configuration snippets,
- the affected version or branch, if known.

Feature requests should describe the use case and the expected behavior instead of only describing an implementation detail.

## Releases

Release preparation work should happen on release branches.

Release branch format:

```text
release/vX.Y.Z
```

Example:

```text
release/v1.0.1
```

Version identifiers follow the `vX.Y.Z` format, for example:

```text
v1.0.1
```

When the changes for a version are complete:

1. finalize the release branch,
2. open a pull request from the release branch into `main`,
3. merge the release changes into `main`,
4. create the release,
5. update and publish Docker images.

Release branches should only contain changes intended for that release.

## Documentation

Documentation should be updated when a change affects:

- setup,
- configuration,
- deployment,
- API behavior,
- authentication,
- authorization,
- database schema,
- security behavior,
- CI/CD behavior.

Documentation should be technical, accurate, and written in English.

## Code Style

Follow the existing project structure and style.

General expectations:

- keep handlers in `handlers/`,
- keep database access in `storage/`,
- keep shared types in `models/`,
- keep authentication helpers in `auth/`,
- keep frontend behavior in `frontend/assets/js/`,
- keep server route wiring in `server/`,
- use clear names,
- avoid unrelated rewrites,
- keep changes as small as reasonably possible.

Go code must be formatted with:

```bash
gofmt -w .
```

## Validation

Before opening a pull request, run the checks that are relevant to the change.

Recommended commands:

```bash
gofmt -w .
go test ./...
go vet ./...
```

If the change affects Docker deployment, also verify that the Docker image builds successfully.

## Security-Relevant Changes

Changes affecting authentication, authorization, session handling, 2FA, recovery codes, cookies, rate limiting, or database security should be kept especially focused.

Security-sensitive pull requests should clearly explain:

- what behavior changed,
- what threat or issue is addressed,
- whether sessions, tokens, or stored secrets are affected,
- whether existing users or deployments need migration steps.

Do not include secrets, private keys, real tokens, production database files, or private configuration values in commits or pull requests.