102 lines
3.8 KiB
Markdown
102 lines
3.8 KiB
Markdown
---
|
|
title: "GULAG"
|
|
subtitle: "Guidelines & Unified Laws for Advanced Gitflow"
|
|
author: "Rémi Heredero"
|
|
template: "darko"
|
|
---
|
|
|
|
# General
|
|
- Git history **has** to be kept linear. Branches **have** to be __rebased__ before being merged.
|
|
- Merge commit is stricly forbidden.
|
|
- Force pushes are disallowed on shared branches unless discussed beforehand with affected people.
|
|
|
|
# Branches
|
|
Branch names *should* be prefixed by a type and the scope. For example:
|
|
- `feat/nodes/sleep-mode`: implements a new feature
|
|
- `fix/gateway/lost-messages`: fixes a bug or issue
|
|
- `refactor/db/endpoints`: modifies the code structure without adding new features
|
|
|
|
<!--pagebreak-->
|
|
|
|
# Pull Requests
|
|
- Branches **must** be merged into the main branch through a pull request.
|
|
- Pull requests *should* be kept relatively short.
|
|
- They **must** be reviewed by at least one other person.
|
|
- They **must** have a meaningful title, summarizing the features or fixes it contains, and can have a more in-depth description to help reviewers understand the contents
|
|
- If a pull request is related to an existing issue or task, its description *should* contain its reference. For example:
|
|
|
|
```
|
|
fix(gateway): lost messages
|
|
|
|
This PR fixes the dropping of incoming messages in the gateway during high-traffic bursts before they can be published to the MQTT broker.
|
|
|
|
The internal buffer was too small (size 5). A slight increase to 15 solves the issue.
|
|
|
|
This PR also adds logging when the limits of 10 and 15 messages are reached, to help understand the root cause if the problem happens again.
|
|
|
|
Fixes: #42
|
|
```
|
|
|
|
A branch that has been merged **must** be deleted.
|
|
|
|
# Commits
|
|
## Content
|
|
- A commit *should* be an atomic change targeting only 1 specific subject.
|
|
- Build artifacts, cache directories, large files, personal configuration, environment variables and secrets **must** not be committed.
|
|
If possible, such files *should* be added to `.gitignore` to avoid accidentally committing them.
|
|
- External libraries, especially large packages, *should* either not be included in the repository (with installation steps), or integrated as Git [submodules](https://github.blog/open-source/git/working-with-submodules/).
|
|
|
|
## Message
|
|
Commit messages **must** follow the [conventional commit format](https://www.conventionalcommits.org/en/v1.0.0/).
|
|
In short, commit messages **must** be structured as follows:
|
|
|
|
```
|
|
<type>(scope): <description>
|
|
|
|
[optional body]
|
|
|
|
[optional footer(s)]
|
|
```
|
|
|
|
The type element describes the content of the commit. The following values are accepted:
|
|
- `fix`: patches a bug / issue
|
|
- `feat`: introduces a new feature
|
|
- `doc` or `docs`: only affects documentation
|
|
- `chore`: small changes to the repository which do not directly affect code or documentation
|
|
- `ci`: modifies CI/CD workflow configuration
|
|
- `refactor`: modifies existing code without changing the results / features
|
|
|
|
Some other types can be accepted but the above list should suffice in most cases.
|
|
The description (or subject) should be kept short.
|
|
An optional body can be added to provide more details.
|
|
It *should* be written in the imperative present tense:
|
|
- ✅️ add database schema
|
|
- ❌ changed path resolution
|
|
- ❌️ fixes rounding error
|
|
|
|
The end of the body can contain special keywords to indicate that it completes a specific issue or task, for example:
|
|
- Closes #42
|
|
- Fixes #4
|
|
- Resolves #38
|
|
|
|
## Authors
|
|
In cases where a commit is written by multiple people, footers **must** be added to indicate co-authors:
|
|
|
|
```
|
|
feat(nodes): implement sleep mode
|
|
|
|
Co-Authored-By: John Doe <john.doe@example.com>
|
|
```
|
|
|
|
If a commit is partly written by an LLM, a footer tag `Assisted-by: AGENT_NAME:MODEL_VERSION` **must** be added, for example:
|
|
|
|
```
|
|
refactor(db): simplify endpoints routing
|
|
|
|
Assisted-by: Claude:claude-3-opus
|
|
```
|
|
|
|
|
|
# Credits
|
|
These guidelines are largely based on the [GitHub policy of the Duckify project](https://toys-r-us-rex.github.io/Duckify/architecture/github_policy.pdf)
|