From afea712f43af10bc21ec015494e5c705c13ae3a4 Mon Sep 17 00:00:00 2001 From: miaurizius Date: Wed, 10 Jun 2026 02:17:50 +0200 Subject: [PATCH] docs: add contribution guidelines --- CONTRIBUTING.md | 238 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 1 + 2 files changed, 239 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..1643745 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,238 @@ +# 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 +/- +``` + +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. diff --git a/README.md b/README.md index ee2575c..68cd0c7 100644 --- a/README.md +++ b/README.md @@ -105,6 +105,7 @@ More detailed documentation is available in: - [Authentication](docs/AUTHENTICATION.md) - [Database](docs/DATABASE.md) - [Security](docs/SECURITY.md) +- [Contributing](CONTRIBUTING.md) ## Configuration -- 2.49.1