From ff98ca5a15b2e5c9bf5df4e12db4aa2d56277575 Mon Sep 17 00:00:00 2001
From: Klagarge <remi@heredero.ch>
Date: Thu, 19 Mar 2026 12:34:45 +0100
Subject: [PATCH] doc: add Guideline & Unified Laws for Advanced Gitflow

---
 GULAG.md | 95 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 95 insertions(+)
 create mode 100644 GULAG.md

diff --git a/GULAG.md b/GULAG.md
new file mode 100644
index 0000000..57eabad
--- /dev/null
+++ b/GULAG.md
@@ -0,0 +1,95 @@
+# G.U.L.A.G. : Guidelines & Unified Laws for Advanced Gitflow
+
+## 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
+
+
+## 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)