miaurizius
afea712f43
Some checks failed
test-and-lint / test-and-lint (pull_request) Failing after 6s
239 lines
6.2 KiB
Markdown
239 lines
6.2 KiB
Markdown
# 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.
|