MiauInv/CONTRIBUTING.md

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:

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

To check whether commits are signed:

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:

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

Examples:

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:

release/vX.Y.Z

Example:

release/v1.0.1

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

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:

gofmt -w .

Validation

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

Recommended commands:

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.