docs: add contribution guidelines
Some checks failed
test-and-lint / test-and-lint (pull_request) Failing after 6s
Some checks failed
test-and-lint / test-and-lint (pull_request) Failing after 6s
This commit is contained in:
238
CONTRIBUTING.md
Normal file
238
CONTRIBUTING.md
Normal file
@@ -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
|
||||
<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.
|
||||
Reference in New Issue
Block a user