From 157d45b5d77845b4b7534e54d2190f7e366419cc Mon Sep 17 00:00:00 2001 From: Mathieu <39670015+mathieusouflis@users.noreply.github.com> Date: Wed, 1 Jul 2026 22:46:01 +0200 Subject: [PATCH 1/9] docs: add domain x type documentation structure --- docs/README.md | 14 +++ docs/operations/concept/ci-cd-pipeline.md | 45 ++++++++ .../runbooks/todo_deployment-runbook.md | 51 +++++++++ .../concept/todo_role-charter.md | 31 +++++ .../decisions/todo_tooling-choice.md | 36 ++++++ .../reference/todo_tool-inventory.md | 31 +++++ .../concept/todo_architecture-overview.md | 32 ++++++ .../todo_first-architecture-decision.md | 42 +++++++ docs/product-code/reference/code-style.md | 107 ++++++++++++++++++ .../reference/environment-variables.md | 32 ++++++ .../product-code/tutorials/getting-started.md | 104 +++++++++++++++++ .../team-process/how-to/activate-git-hooks.md | 36 ++++++ .../reference/commit-conventions.md | 53 +++++++++ .../reference/pull-request-process.md | 59 ++++++++++ 14 files changed, 673 insertions(+) create mode 100644 docs/README.md create mode 100644 docs/operations/concept/ci-cd-pipeline.md create mode 100644 docs/operations/runbooks/todo_deployment-runbook.md create mode 100644 docs/organizational/concept/todo_role-charter.md create mode 100644 docs/organizational/decisions/todo_tooling-choice.md create mode 100644 docs/organizational/reference/todo_tool-inventory.md create mode 100644 docs/product-code/concept/todo_architecture-overview.md create mode 100644 docs/product-code/decisions/todo_first-architecture-decision.md create mode 100644 docs/product-code/reference/code-style.md create mode 100644 docs/product-code/reference/environment-variables.md create mode 100644 docs/product-code/tutorials/getting-started.md create mode 100644 docs/team-process/how-to/activate-git-hooks.md create mode 100644 docs/team-process/reference/commit-conventions.md create mode 100644 docs/team-process/reference/pull-request-process.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..ae01f9b --- /dev/null +++ b/docs/README.md @@ -0,0 +1,14 @@ +# Documentation + +Organized by two axes: **domain** (what this document is about) and **type** (what shape it takes / what the reader is trying to do). A document always lives at the intersection of both — e.g. `product-code/reference/` is a lookup table about the code, `team-process/how-to/` is a step-by-step guide about how the team works. + +| Type →
Domain ↓ | Concept | How-to | Reference | Decisions | Tutorials | Runbooks | +|---|---|---|---|---|---|---| +| **[product-code](product-code/)** | [Architecture overview](product-code/concept/todo_architecture-overview.md) 🚧 | — | [Code style](product-code/reference/code-style.md), [Environment variables](product-code/reference/environment-variables.md) | [First decision](product-code/decisions/todo_first-architecture-decision.md) 🚧 | [Getting started](product-code/tutorials/getting-started.md) | — | +| **[operations](operations/)** | [CI/CD pipeline](operations/concept/ci-cd-pipeline.md) | — | — | — | — | [Deployment](operations/runbooks/todo_deployment-runbook.md) 🚧 | +| **[team-process](team-process/)** | — | [Activate Git hooks](team-process/how-to/activate-git-hooks.md) | [Commit conventions](team-process/reference/commit-conventions.md), [PR process](team-process/reference/pull-request-process.md) | — | — | — | +| **[organizational](organizational/)** | [Role charter](organizational/concept/todo_role-charter.md) 🚧 | — | [Tool inventory](organizational/reference/todo_tool-inventory.md) 🚧 | [Tooling choice](organizational/decisions/todo_tooling-choice.md) 🚧 | — | — | + +🚧 = template placeholder (`todo_` prefix), no real content yet — see the note inside each file for what to fill in and how to rename it once done. + +A few things intentionally live outside this grid, at fixed paths GitHub itself expects: [`README.md`](../README.md), [`CONTRIBUTING.md`](../CONTRIBUTING.md), [`CODE_OF_CONDUCT.md`](../CODE_OF_CONDUCT.md), [`SECURITY.md`](../SECURITY.md), [`LICENSE`](../LICENSE), and [`.github/CODEOWNERS`](../.github/CODEOWNERS). Moving them would break the platform features tied to those paths (Security tab, community profile checklist, the PR-open banner). Each links into this grid for detail rather than duplicating it. diff --git a/docs/operations/concept/ci-cd-pipeline.md b/docs/operations/concept/ci-cd-pipeline.md new file mode 100644 index 0000000..3efc970 --- /dev/null +++ b/docs/operations/concept/ci-cd-pipeline.md @@ -0,0 +1,45 @@ +--- +domain: operations +type: concept +owner: +last_reviewed: +--- + +# CI/CD Pipeline + +How this repository validates and ships changes, as actually configured under `.github/workflows/` and `.githooks/` today. + +## Continuous Integration — `.github/workflows/ci.yml` + +Runs on every push to `main` and every pull request targeting `main`. Three jobs, each on a fresh runner: + +| Job | Purpose | +|---|---| +| `lint` | Runtime setup, dependency install, lint/type-check | +| `test` | Runtime setup, dependency install, test suite | +| `build` | Runs after `lint` and `test` pass; runtime setup, dependency install, build | + +**This workflow ships as a placeholder** — every step currently runs `echo "Replace this step with..."` instead of a real command. It is language-agnostic by construction: fill in the runtime-setup action (`actions/setup-node`, `actions/setup-python`, `actions/setup-go`, etc.) and the install/lint/test/build commands for your stack, then delete the template comment block at the top of the file. + +## Commit message validation — `.githooks/commit-msg` + `.github/workflows/commitlint.yml` + +Commit messages are validated against Conventional Commits **twice**, both reusing the exact same shell script (`.githooks/commit-msg`) so there is one source of truth for the rule rather than two that can drift apart: + +- **Locally**, if the contributor activated the hook (`git config core.hooksPath .githooks`) — fast feedback, but optional and easy to skip. +- **In CI**, on every pull request — the `commitlint.yml` workflow re-runs the same script against every commit in the PR, so a contributor who never activated the local hook is still caught before merge. + +See [team-process/reference/commit-conventions](../../team-process/reference/commit-conventions.md) for the rule itself. + +## Release — `.github/workflows/release.yml` + +Triggered by pushing a tag matching `v*.*.*`. Creates a GitHub Release with auto-generated release notes from the commit history (`generate_release_notes: true`) — no manual changelog editing required, provided commits follow the Conventional Commits format enforced above. + +## Dependency updates — `.github/dependabot.yml` + +Two ecosystems are always active regardless of language: `github-actions` (workflow action versions) and `docker`, both checked monthly. Language-specific ecosystems (`npm`, `pip`, `gomod`, `cargo`, `maven`, `gradle`, `composer`, `bundler`) are present but commented out — uncomment the one matching this project's stack. + +## See also + +- [team-process/reference/commit-conventions](../../team-process/reference/commit-conventions.md) +- [team-process/how-to/activate-git-hooks](../../team-process/how-to/activate-git-hooks.md) +- [operations/runbooks](../runbooks/) diff --git a/docs/operations/runbooks/todo_deployment-runbook.md b/docs/operations/runbooks/todo_deployment-runbook.md new file mode 100644 index 0000000..2b36e83 --- /dev/null +++ b/docs/operations/runbooks/todo_deployment-runbook.md @@ -0,0 +1,51 @@ +--- +domain: operations +type: runbook +status: todo +owner: +last_exercised: +--- + +# TODO — Deployment runbook + + + +## When to use this runbook + + + +## Prerequisites + + + +## Steps + +1. + +## Verification + + + +## Rollback + + + +## Last exercised + + + +## See also + +- [operations/concept/ci-cd-pipeline](../concept/ci-cd-pipeline.md) diff --git a/docs/organizational/concept/todo_role-charter.md b/docs/organizational/concept/todo_role-charter.md new file mode 100644 index 0000000..0f2aace --- /dev/null +++ b/docs/organizational/concept/todo_role-charter.md @@ -0,0 +1,31 @@ +--- +domain: organizational +type: concept +status: todo +owner: +last_reviewed: +--- + +# TODO — Role Charter + + + +## What to cover here + +- What this role/team owns — the boundary of its decision-making authority, not just its day-to-day tasks +- What it explicitly does **not** own, where that's likely to be assumed incorrectly +- Who currently holds the role (a name is fine here in prose, but ownership in frontmatter across this project stays team/role-based, never an individual — see the ownership convention repeated across every file in this tree) +- How this role interacts with adjacent roles/teams + +## See also + +- [organizational/reference/todo_tool-inventory](../reference/todo_tool-inventory.md) +- [.github/CODEOWNERS](../../../.github/CODEOWNERS) diff --git a/docs/organizational/decisions/todo_tooling-choice.md b/docs/organizational/decisions/todo_tooling-choice.md new file mode 100644 index 0000000..8a70495 --- /dev/null +++ b/docs/organizational/decisions/todo_tooling-choice.md @@ -0,0 +1,36 @@ +--- +domain: organizational +type: decision-record +status: todo +owner: +supersedes: +--- + +# TODO — Title of the decision, as a short noun phrase + + + +## Context + + + +## Decision + + + +## Consequences + + + +## Superseded by + + diff --git a/docs/organizational/reference/todo_tool-inventory.md b/docs/organizational/reference/todo_tool-inventory.md new file mode 100644 index 0000000..1827e71 --- /dev/null +++ b/docs/organizational/reference/todo_tool-inventory.md @@ -0,0 +1,31 @@ +--- +domain: organizational +type: reference +status: todo +owner: +last_reviewed: +--- + +# TODO — Tool Inventory + + + +| Tool | Used for | Owner | Alternatives considered | +|---|---|---|---| +| GitHub | Source control, CI/CD, issue tracking | | — | +| | | | | + +## See also + +- [organizational/decisions](../decisions/) — why a given tool was chosen over alternatives +- [.github/CODEOWNERS](../../../.github/CODEOWNERS) — per-path ownership (GitHub-native, kept at its required path) diff --git a/docs/product-code/concept/todo_architecture-overview.md b/docs/product-code/concept/todo_architecture-overview.md new file mode 100644 index 0000000..3cf0db2 --- /dev/null +++ b/docs/product-code/concept/todo_architecture-overview.md @@ -0,0 +1,32 @@ +--- +domain: product-code +type: concept +status: todo +owner: +last_reviewed: +--- + +# Architecture Overview + + + +## What to cover here + +- The main components/modules and how they talk to each other (a diagram earns its place here if there are 3+ interacting parts) +- The data flow for the system's core use case, end to end +- The key constraints that shaped the design (scale, latency, team size, compliance) — the "why", not just the "what" +- Links to the [Decision Records](../decisions/) that explain individual architectural choices in detail — this file is the map, the decisions are the reasoning + +## See also + +- [product-code/decisions](../decisions/) — individual architectural choices +- [product-code/reference](../reference/) — concrete API/schema/config lookup diff --git a/docs/product-code/decisions/todo_first-architecture-decision.md b/docs/product-code/decisions/todo_first-architecture-decision.md new file mode 100644 index 0000000..c16b5a5 --- /dev/null +++ b/docs/product-code/decisions/todo_first-architecture-decision.md @@ -0,0 +1,42 @@ +--- +domain: product-code +type: decision-record +status: todo +owner: +supersedes: +--- + +# TODO — Title of the decision, as a short noun phrase + + + +## Context + + + +## Decision + + + +## Consequences + + + +## Superseded by + + diff --git a/docs/product-code/reference/code-style.md b/docs/product-code/reference/code-style.md new file mode 100644 index 0000000..6969b65 --- /dev/null +++ b/docs/product-code/reference/code-style.md @@ -0,0 +1,107 @@ +--- +domain: product-code +type: reference +owner: +last_reviewed: +--- + +# Code Style Guide + + + +This document defines the code style and formatting conventions for this project. Consistency matters more than any individual rule — when in doubt, follow existing patterns in the codebase. + +--- + +## Tooling + + + +```bash +# Check for style errors +# Auto-fix formatting +``` + +All checks must pass before a PR can be merged. The CI pipeline enforces this automatically — see [operations/concept/ci-cd-pipeline](../../operations/concept/ci-cd-pipeline.md). + +--- + +## General Principles + +- **Clarity over cleverness** — write code for the next reader, not the compiler +- **Explicit over implicit** — avoid magic; name things for what they do +- **Small functions** — each function should do one thing +- **No dead code** — remove commented-out code before committing + +--- + +## Naming Conventions + + + +| Element | Convention | Example | +|---------|------------|---------| +| Files | `kebab-case` | `user-service.ts` | +| Classes | `PascalCase` | `UserService` | +| Functions / methods | `camelCase` | `getUserById` | +| Constants | `UPPER_SNAKE_CASE` | `MAX_RETRY_COUNT` | +| Private members | `_prefixed` or language convention | `_cache` | + +--- + +## Formatting + + + +- **Indentation**: X spaces (no tabs) +- **Max line length**: 100 characters +- **Trailing commas**: yes / no +- **Quotes**: single / double + +--- + +## Import / Dependency Order + + + +1. Standard library / built-ins +2. Third-party packages +3. Internal packages / modules +4. Relative imports + +Separate each group with a blank line. + +--- + +## Error Handling + +- Never swallow errors silently — log or propagate +- Use typed/structured errors where the language supports it +- Validate inputs at system boundaries; trust internal code + +--- + +## Testing Conventions + +- Tests live next to the code they test, or in a dedicated `tests/` directory +- Each test should be independent and not rely on shared mutable state +- Test names should describe the expected behavior: `should return 404 when user not found` + +--- + +## Running the Full Validation Suite + +```bash +# Replace with your actual commands +# Lint +# Type-check (if applicable) +# Tests +# Build +``` + +All four must pass before pushing. + +## See also + +- [operations/concept/ci-cd-pipeline](../../operations/concept/ci-cd-pipeline.md) — how these checks run in CI +- [product-code/tutorials/getting-started](../tutorials/getting-started.md) diff --git a/docs/product-code/reference/environment-variables.md b/docs/product-code/reference/environment-variables.md new file mode 100644 index 0000000..39f8138 --- /dev/null +++ b/docs/product-code/reference/environment-variables.md @@ -0,0 +1,32 @@ +--- +domain: product-code +type: reference +owner: +last_reviewed: +--- + +# Environment Variables + +Every variable this project reads from its environment, generated from [`.env.example`](../../../.env.example) at the repository root. **This file must stay in sync with `.env.example`** — the reference is only useful if it matches the code, so update both in the same PR whenever a variable is added, renamed, or removed. + +| Variable | Required | Default | Description | +|----------|----------|---------|-------------| +| `PORT` | No | `3000` | Port the server listens on — only applies if this project runs a network service; remove otherwise | +| `HOST` | No | `0.0.0.0` | Host/interface the server binds to — only applies if this project runs a network service; remove otherwise | +| `DATABASE_URL` | | — | Connection string for the database | +| `JWT_SECRET` | | `change-me-before-deploying` | Secret used to sign/verify auth tokens — **must** be overridden in every real environment | +| | | | | + +--- + +## Setup + +```bash +cp .env.example .env +``` + +Then fill in every value above marked `Required: `. Never commit the `.env` file — it is listed in `.gitignore`. + +## See also + +- [product-code/tutorials/getting-started](../tutorials/getting-started.md) diff --git a/docs/product-code/tutorials/getting-started.md b/docs/product-code/tutorials/getting-started.md new file mode 100644 index 0000000..9acc411 --- /dev/null +++ b/docs/product-code/tutorials/getting-started.md @@ -0,0 +1,104 @@ +--- +domain: product-code +type: tutorial +owner: +last_reviewed: +--- + +# Getting Started + + + +This guide walks a new contributor from zero to a running local environment. It assumes no prior context — for a specific task you already know how to do (e.g. "add an endpoint"), see [product-code/reference](../reference/) instead. + +--- + +## Prerequisites + + + +| Tool | Version | Install | +|------|---------|---------| +| | | | +| | | | + +--- + +## Setup + +1. **Clone the repository** + + ```bash + git clone https://github.com/your-org/your-repo.git + cd your-repo + ``` + +2. **Activate the Git hooks** (one-time, after cloning) + + ```bash + git config core.hooksPath .githooks + ``` + + Details: [team-process/how-to/activate-git-hooks](../../team-process/how-to/activate-git-hooks.md). + +3. **Copy the environment file** + + ```bash + cp .env.example .env + ``` + + Open `.env` and fill in the required values — see [product-code/reference/environment-variables](../reference/environment-variables.md). + +4. **Install dependencies** + + ```bash + # Replace with your package manager / build tool + # e.g. npm install / pip install -r requirements.txt / go mod download / mvn install + ``` + +5. **Start the development server** + + ```bash + # Replace with your start command + # e.g. npm run dev / python manage.py runserver / go run ./cmd/server + ``` + +--- + +## Common Commands + + + +```bash +# Start development server +# Run tests +# Run linter +# Build for production +``` + +--- + +## Troubleshooting + +**Port already in use** + +Find and stop the process occupying the port before starting the server. + +**Dependencies not installing** + +Make sure your runtime version matches the one listed in [Prerequisites](#prerequisites). Delete any lock files and retry a fresh install. + +**Tests fail locally but pass in CI (or vice versa)** + +Make sure your `.env` matches the values expected by the test suite, and reinstall dependencies from the lockfile to rule out local drift (e.g. `npm ci` / `pip install -r requirements.txt --no-deps` / `go mod tidy`). + +**Build fails with errors you didn't introduce** + +Pull the latest `main` and reinstall dependencies — a dependency may have been updated since your last build. + +For anything else, open a [Discussion](../../../../discussions). + +## See also + +- [product-code/reference/environment-variables](../reference/environment-variables.md) +- [team-process/how-to/activate-git-hooks](../../team-process/how-to/activate-git-hooks.md) diff --git a/docs/team-process/how-to/activate-git-hooks.md b/docs/team-process/how-to/activate-git-hooks.md new file mode 100644 index 0000000..d1d2ec3 --- /dev/null +++ b/docs/team-process/how-to/activate-git-hooks.md @@ -0,0 +1,36 @@ +--- +domain: team-process +type: how-to +owner: +last_reviewed: +--- + +# How to Activate the Git Hooks + +This repo ships two shell-based hooks under `.githooks/` — no runtime or dependencies required, so they work identically regardless of the project's language. + +## Steps + +1. From the repository root, run: + + ```bash + git config core.hooksPath .githooks + ``` + +2. That's it — this is a one-time, per-clone setting stored in your local Git config, not committed to the repo. + +## What each hook does + +| Hook | Runs on | Purpose | +|---|---|---| +| `commit-msg` | every `git commit` | Rejects commit messages that don't follow [Conventional Commits](../reference/commit-conventions.md) | +| `pre-push` | every `git push` | Placeholder — uncomment the test/build checks inside `.githooks/pre-push` to run them before every push | + +## Why this is optional but recommended + +Activating the hook is not required to contribute — `commit-msg` validation also runs in CI on every pull request as a backstop, so a bad commit message is still caught before merge even if you skip this step. Activating it locally just gives you the same feedback earlier, before you push. + +## See also + +- [team-process/reference/commit-conventions](../reference/commit-conventions.md) +- [operations/concept/ci-cd-pipeline](../../operations/concept/ci-cd-pipeline.md) diff --git a/docs/team-process/reference/commit-conventions.md b/docs/team-process/reference/commit-conventions.md new file mode 100644 index 0000000..a306796 --- /dev/null +++ b/docs/team-process/reference/commit-conventions.md @@ -0,0 +1,53 @@ +--- +domain: team-process +type: reference +owner: +last_reviewed: +--- + +# Commit Conventions + +We follow **Conventional Commits**, enforced automatically — see [operations/concept/ci-cd-pipeline](../../operations/concept/ci-cd-pipeline.md) for how. Each commit message should be: + +``` +(): + +[optional body] + +[optional footer] +``` + +**Types:** + +| Type | When to use | +|------------|----------------------------------------| +| `feat` | New feature or behavior | +| `fix` | Bug fix | +| `refactor` | Code change with no behavior change | +| `test` | Adding or updating tests | +| `docs` | Documentation only | +| `chore` | Tooling, dependencies, config | +| `perf` | Performance improvement | +| `ci` | CI/CD changes | + +**Scope** (optional): the module or area affected, e.g. `auth`, `api`, `ui`, `docker`. + +**Examples:** +``` +feat(auth): add refresh token revocation on logout +fix(api): return 409 when resource already exists +refactor(core): extract validation to separate utility +test(auth): add unit tests for login use case +docs(setup): add environment variable reference +chore(deps): upgrade dependencies +``` + +**Rules:** +- Use the **imperative mood** ("add" not "adds" or "added") +- Keep the first line under **72 characters** +- Reference issues in the footer: `Closes #42`, `Fixes #17` + +## See also + +- [team-process/how-to/activate-git-hooks](../how-to/activate-git-hooks.md) +- [operations/concept/ci-cd-pipeline](../../operations/concept/ci-cd-pipeline.md) diff --git a/docs/team-process/reference/pull-request-process.md b/docs/team-process/reference/pull-request-process.md new file mode 100644 index 0000000..a33d23a --- /dev/null +++ b/docs/team-process/reference/pull-request-process.md @@ -0,0 +1,59 @@ +--- +domain: team-process +type: reference +owner: +last_reviewed: +--- + +# Pull Request Process + +## Reporting bugs + +Before opening an issue: +- Search [existing issues](../../../../issues) to avoid duplicates +- Make sure you are on the latest version (`git pull upstream main`) + +When opening a bug report, use the **Bug Report** template and include: +- Steps to reproduce +- Expected vs actual behavior +- Your environment (OS, runtime version, relevant tool versions) +- Relevant logs or screenshots + +## Suggesting features + +Open a **Feature Request** issue with: +- A clear description of the problem the feature solves +- Your proposed solution +- Alternatives you considered + +Features that align with the project's scope and architecture are more likely to be accepted. + +## Submitting code changes + +1. Create a branch from `main`: + ```bash + git checkout main + git pull upstream main + git checkout -b feat/your-feature-name + ``` +2. Make your changes following [product-code/reference/code-style](../../product-code/reference/code-style.md) +3. Write or update tests — every PR should maintain or improve existing coverage +4. Run the validation suite locally (see [product-code/tutorials/getting-started](../../product-code/tutorials/getting-started.md)) +5. Commit following [team-process/reference/commit-conventions](commit-conventions.md) +6. Push and open a Pull Request + +## Review and merge + +- **One PR per concern** — don't mix unrelated changes +- **Fill the PR template** — describe what changed and why +- **Keep diffs small** — large PRs are hard to review; split if needed. Aim for something reviewable in under 30 minutes +- **All CI checks must pass** before merging +- **Address review comments** — don't force-merge, iterate on feedback +- **Squash or rebase** before merge if history is messy + +PRs are merged by maintainers once they have one approving review and all checks are green — see [organizational/reference](../../organizational/reference/) for who that is on this project. + +## See also + +- [product-code/reference/code-style](../../product-code/reference/code-style.md) +- [team-process/reference/commit-conventions](commit-conventions.md) From 20ba2b6a71ebb2609aec3605ddd8cfca1f80083e Mon Sep 17 00:00:00 2001 From: Mathieu <39670015+mathieusouflis@users.noreply.github.com> Date: Wed, 1 Jul 2026 22:46:09 +0200 Subject: [PATCH 2/9] docs: remove legacy getting-started and developer-guide docs --- docs/developer-guide/faq.md | 51 ---------- docs/developer-guide/guidelines/code-style.md | 95 ------------------- docs/getting-started/README.md | 91 ------------------ 3 files changed, 237 deletions(-) delete mode 100644 docs/developer-guide/faq.md delete mode 100644 docs/developer-guide/guidelines/code-style.md delete mode 100644 docs/getting-started/README.md diff --git a/docs/developer-guide/faq.md b/docs/developer-guide/faq.md deleted file mode 100644 index 9b76b8e..0000000 --- a/docs/developer-guide/faq.md +++ /dev/null @@ -1,51 +0,0 @@ -# FAQ - -Frequently asked questions about developing in this project. - ---- - -## General - -**Q: Where do I start?** -See [Getting Started](../getting-started/README.md) for the full setup guide. - -**Q: I found a bug. How do I report it?** -Open a [Bug Report issue](../../../issues/new/choose) using the provided template. - -**Q: I want to add a feature. Where do I begin?** -Open a [Feature Request issue](../../../issues/new/choose) first to discuss the idea before writing code. - ---- - -## Development - -**Q: Tests are failing locally but passing in CI (or vice versa).** -- Make sure your `.env` matches the values expected by the test suite -- Reinstall dependencies from the lockfile to rule out a local drift - - -**Q: How do I run a single test file?** -```bash -# Replace with your test runner's single-file invocation -# e.g. npm test -- path/to/file.test.ts / pytest path/to/test_file.py / go test ./path/... -``` - -**Q: The build fails with errors I didn't introduce.** -Pull the latest `main` and reinstall dependencies — one may have been updated since you last built. - ---- - -## Contributing - -**Q: How large should a PR be?** -Aim for PRs that can be reviewed in under 30 minutes. Split larger changes into multiple PRs if possible. - -**Q: Do I need to write tests for every change?** -Yes for new features and bug fixes. Documentation-only PRs are exempt. - -**Q: Who merges PRs?** -Maintainers merge PRs once they have one approving review and all CI checks are green. - ---- - -Still stuck? Open a [Discussion](../../../discussions). diff --git a/docs/developer-guide/guidelines/code-style.md b/docs/developer-guide/guidelines/code-style.md deleted file mode 100644 index 7153700..0000000 --- a/docs/developer-guide/guidelines/code-style.md +++ /dev/null @@ -1,95 +0,0 @@ -# Code Style Guide - - - -This document defines the code style and formatting conventions for this project. Consistency matters more than any individual rule — when in doubt, follow existing patterns in the codebase. - ---- - -## Tooling - - - -```bash -# Check for style errors -# Auto-fix formatting -``` - -All checks must pass before a PR can be merged. The CI pipeline enforces this automatically. - ---- - -## General Principles - -- **Clarity over cleverness** — write code for the next reader, not the compiler -- **Explicit over implicit** — avoid magic; name things for what they do -- **Small functions** — each function should do one thing -- **No dead code** — remove commented-out code before committing - ---- - -## Naming Conventions - - - -| Element | Convention | Example | -|---------|------------|---------| -| Files | `kebab-case` | `user-service.ts` | -| Classes | `PascalCase` | `UserService` | -| Functions / methods | `camelCase` | `getUserById` | -| Constants | `UPPER_SNAKE_CASE` | `MAX_RETRY_COUNT` | -| Private members | `_prefixed` or language convention | `_cache` | - ---- - -## Formatting - - - -- **Indentation**: X spaces (no tabs) -- **Max line length**: 100 characters -- **Trailing commas**: yes / no -- **Quotes**: single / double - ---- - -## Import / Dependency Order - - - -1. Standard library / built-ins -2. Third-party packages -3. Internal packages / modules -4. Relative imports - -Separate each group with a blank line. - ---- - -## Error Handling - -- Never swallow errors silently — log or propagate -- Use typed/structured errors where the language supports it -- Validate inputs at system boundaries; trust internal code - ---- - -## Testing Conventions - -- Tests live next to the code they test, or in a dedicated `tests/` directory -- Each test should be independent and not rely on shared mutable state -- Test names should describe the expected behavior: `should return 404 when user not found` - ---- - -## Running the Full Validation Suite - -```bash -# Replace with your actual commands -# Lint -# Type-check (if applicable) -# Tests -# Build -``` - -All four must pass before pushing. diff --git a/docs/getting-started/README.md b/docs/getting-started/README.md deleted file mode 100644 index b0d23ef..0000000 --- a/docs/getting-started/README.md +++ /dev/null @@ -1,91 +0,0 @@ -# Getting Started - -This guide walks you through setting up the project locally for development. - ---- - -## Prerequisites - - - -| Tool | Version | Install | -|------|---------|---------| -| | | | -| | | | - ---- - -## Setup - -1. **Clone the repository** - - ```bash - git clone https://github.com/your-org/your-repo.git - cd your-repo - ``` - -2. **Activate the commit-msg hook** (one-time, after cloning) - - ```bash - git config core.hooksPath .githooks - ``` - -3. **Copy the environment file** - - ```bash - cp .env.example .env - ``` - - Open `.env` and fill in the required values. See [Environment Variables](#environment-variables) below. - -4. **Install dependencies** - - ```bash - # Replace with your package manager / build tool - # e.g. npm install / pip install -r requirements.txt / go mod download / mvn install - ``` - -5. **Start the development server** - - ```bash - # Replace with your start command - # e.g. npm run dev / python manage.py runserver / go run ./cmd/server - ``` - ---- - -## Environment Variables - - - -| Variable | Required | Default | Description | -|----------|----------|---------|-------------| -| `PORT` | No | `3000` | Port the server listens on (only if this project runs a network service; remove otherwise) | -| | | | | - ---- - -## Common Commands - - - -```bash -# Start development server -# Run tests -# Run linter -# Build for production -``` - ---- - -## Troubleshooting - -**Port already in use** - -Find and stop the process occupying the port before starting the server. - -**Dependencies not installing** - -Make sure your runtime version matches the one listed in [Prerequisites](#prerequisites). Delete any lock files and retry a fresh install. - -For other issues, check the [FAQ](../developer-guide/faq.md) or open a [Discussion](../../../discussions). From 246cb20f81db23c8051273a668e657e5eb80de3e Mon Sep 17 00:00:00 2001 From: Mathieu <39670015+mathieusouflis@users.noreply.github.com> Date: Wed, 1 Jul 2026 22:46:15 +0200 Subject: [PATCH 3/9] docs(readme): point README and CONTRIBUTING at new docs structure --- CONTRIBUTING.md | 144 +++--------------------------------------------- README.md | 48 +++++----------- 2 files changed, 20 insertions(+), 172 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fcc0a0c..a209646 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,23 +1,6 @@ # Contributing -Thank you for your interest in contributing! This document explains how to get involved, what we expect, and how to get your changes merged. - ---- - -## Table of Contents - -- [Code of Conduct](#code-of-conduct) -- [Getting Started](#getting-started) -- [Development Setup](#development-setup) -- [How to Contribute](#how-to-contribute) - - [Reporting Bugs](#reporting-bugs) - - [Suggesting Features](#suggesting-features) - - [Activating the commit-msg hook](#activating-the-commit-msg-hook) - - [Submitting Code Changes](#submitting-code-changes) -- [Commit Conventions](#commit-conventions) -- [Pull Request Process](#pull-request-process) -- [Code Style](#code-style) -- [Testing](#testing) +Thank you for your interest in contributing! This document explains how to get involved. Detailed process reference lives in [`docs/team-process/`](docs/team-process/) — this file is the short entry point, not the full spec. --- @@ -39,134 +22,21 @@ This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT. ```bash git remote add upstream https://github.com/your-org/your-repo.git ``` -4. Follow the [development setup guide](docs/getting-started/README.md) - ---- - -## Development Setup - -See [Getting Started](docs/getting-started/README.md) for the full setup guide. +4. Follow the full setup guide: [docs/product-code/tutorials/getting-started](docs/product-code/tutorials/getting-started.md) +5. Activate the Git hooks (one-time, recommended): [docs/team-process/how-to/activate-git-hooks](docs/team-process/how-to/activate-git-hooks.md) --- ## How to Contribute -### Reporting Bugs - -Before opening an issue: -- Search [existing issues](../../issues) to avoid duplicates -- Make sure you are on the latest version (`git pull upstream main`) - -When opening a bug report, use the **Bug Report** template and include: -- Steps to reproduce -- Expected vs actual behavior -- Your environment (OS, runtime version, relevant tool versions) -- Relevant logs or screenshots - -### Suggesting Features - -Open a **Feature Request** issue with: -- A clear description of the problem the feature solves -- Your proposed solution -- Alternatives you considered - -Features that align with the project's scope and architecture are more likely to be accepted. - -### Activating the commit-msg hook - -A shell-based hook validates commit messages locally against the Conventional Commits spec. Activate it once after cloning — no runtime or dependencies required: - -```bash -git config core.hooksPath .githooks -``` - -Commit messages are also validated in CI on every PR via GitHub Actions. - -### Submitting Code Changes - -1. Create a branch from `main`: - ```bash - git checkout main - git pull upstream main - git checkout -b feat/your-feature-name - ``` -2. Make your changes following the [code style](#code-style) guidelines -3. Write or update tests -4. Run the validation suite locally (see [Development Setup](docs/getting-started/README.md)) -5. Commit following [commit conventions](#commit-conventions) -6. Push and open a Pull Request - ---- - -## Commit Conventions - -We follow **Conventional Commits**. Each commit message should be: - -``` -(): - -[optional body] - -[optional footer] -``` - -**Types:** - -| Type | When to use | -|------------|---------------------------------------| -| `feat` | New feature or behavior | -| `fix` | Bug fix | -| `refactor` | Code change with no behavior change | -| `test` | Adding or updating tests | -| `docs` | Documentation only | -| `chore` | Tooling, dependencies, config | -| `perf` | Performance improvement | -| `ci` | CI/CD changes | - -**Scope** (optional): the module or area affected, e.g. `auth`, `api`, `ui`, `docker`. - -**Examples:** -``` -feat(auth): add refresh token revocation on logout -fix(api): return 409 when resource already exists -refactor(core): extract validation to separate utility -test(auth): add unit tests for login use case -docs(setup): add environment variable reference -chore(deps): upgrade dependencies -``` - -**Rules:** -- Use the **imperative mood** ("add" not "adds" or "added") -- Keep the first line under **72 characters** -- Reference issues in the footer: `Closes #42`, `Fixes #17` - ---- - -## Pull Request Process - -1. **One PR per concern** — don't mix unrelated changes -2. **Fill the PR template** — describe what changed and why -3. **Keep diffs small** — large PRs are hard to review; split if needed -4. **All CI checks must pass** before merging -5. **Address review comments** — don't push force-merges; iterate on feedback -6. **Squash or rebase** before merge if history is messy - -PRs are merged by maintainers once they have one approving review and all checks are green. - ---- - -## Code Style - -See [Code Style Guide](docs/developer-guide/guidelines/code-style.md) for detailed conventions. - ---- +Reporting bugs, suggesting features, submitting code changes, and the review/merge process are all covered in one place: [docs/team-process/reference/pull-request-process](docs/team-process/reference/pull-request-process.md). -## Testing +Commit messages follow Conventional Commits, validated automatically both locally (if hooks are activated) and in CI: [docs/team-process/reference/commit-conventions](docs/team-process/reference/commit-conventions.md). -Every PR should maintain or improve the existing test coverage. +Code should follow this project's conventions: [docs/product-code/reference/code-style](docs/product-code/reference/code-style.md). --- ## Questions? -Open a [Discussion](../../discussions) or check the [FAQ](docs/developer-guide/faq.md). +Open a [Discussion](../../discussions). diff --git a/README.md b/README.md index 65c7eac..3e8b30d 100644 --- a/README.md +++ b/README.md @@ -36,60 +36,38 @@ Describe the problem this project solves, its main features, and any key design ## Getting Started -### Prerequisites - - - -| Tool | Version | Install | -|------|---------|---------| -| | | | - -### Installation - ```bash git clone https://github.com/your-org/your-repo.git cd your-repo - -# Activate the commit-msg hook (optional but recommended) -git config core.hooksPath .githooks - -# Copy and fill in environment variables -cp .env.example .env - -# Install dependencies (replace with your package manager) -# e.g. npm install / pip install -r requirements.txt / go mod download +git config core.hooksPath .githooks # activate the Git hooks — optional but recommended +cp .env.example .env # then fill in the values ``` -See [docs/getting-started](docs/getting-started/README.md) for the full setup guide. - ---- - -## Development - -```bash -# Start development server -# Run tests -# Lint / format -# Build for production -``` - - +Full setup guide (prerequisites, dependency install, dev server): [docs/product-code/tutorials/getting-started](docs/product-code/tutorials/getting-started.md). --- ## Architecture -Brief description of the high-level structure. Link to detailed docs if available. + + +See [docs/product-code/concept/todo_architecture-overview](docs/product-code/concept/todo_architecture-overview.md) — template placeholder, not yet filled in. ``` . ├── src/ # Source code -├── docs/ # Documentation +├── docs/ # Documentation — organized by domain × type, see docs/README.md └── .github/ # GitHub configuration ``` --- +## Documentation + +All project documentation lives in [`docs/`](docs/README.md), organized by domain (what it's about) × type (what shape it takes). Start there for anything beyond this quickstart — architecture, environment variables, coding conventions, CI/CD, decisions, and more. + +--- + ## Contributing Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. From 4256a69ea301b068e7f829cab242177af9729f5d Mon Sep 17 00:00:00 2001 From: Mathieu <39670015+mathieusouflis@users.noreply.github.com> Date: Wed, 1 Jul 2026 22:46:20 +0200 Subject: [PATCH 4/9] fix(support): update stale links to new docs structure --- .github/SUPPORT.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/.github/SUPPORT.md b/.github/SUPPORT.md index 269f23e..e91310c 100644 --- a/.github/SUPPORT.md +++ b/.github/SUPPORT.md @@ -4,9 +4,8 @@ Before opening an issue, please check these resources: -1. **[Documentation](../docs/getting-started/README.md)** — setup guide and common commands -2. **[FAQ](../docs/developer-guide/faq.md)** — answers to frequent questions -3. **[Existing issues](../../issues)** — your problem may already be tracked +1. **[Documentation](../docs/README.md)** — setup guide, conventions, and everything else, organized by domain and type +2. **[Existing issues](../../issues)** — your problem may already be tracked ## Asking a question From f695596a4cea0a13e3ea23994ecdc5c3372e141f Mon Sep 17 00:00:00 2001 From: Mathieu <39670015+mathieusouflis@users.noreply.github.com> Date: Wed, 1 Jul 2026 22:46:27 +0200 Subject: [PATCH 5/9] ci: add non-blocking check for unfilled documentation placeholders --- .githooks/pre-push | 13 +++++++++++++ .github/workflows/ci.yml | 20 ++++++++++++++++++++ 2 files changed, 33 insertions(+) diff --git a/.githooks/pre-push b/.githooks/pre-push index 3f9840e..ac93230 100755 --- a/.githooks/pre-push +++ b/.githooks/pre-push @@ -11,4 +11,17 @@ # echo "Running build check..." # your-build-command || exit 1 +# ── Documentation TODOs ───────────────────────────────────────────────── +# Non-blocking: lists template placeholder docs (docs/**/todo_*.md) that +# still need to be filled in, per the domain × type documentation model +# in docs/README.md. Never fails the push — just keeps the remaining work +# visible instead of silently forgotten. +TODO_DOCS=$(find docs -name 'todo_*.md' 2>/dev/null) +if [ -n "$TODO_DOCS" ]; then + echo "" + echo " Documentation still has template placeholders:" + echo "$TODO_DOCS" | sed 's/^/ - /' + echo "" +fi + exit 0 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5575b18..792d79d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -74,3 +74,23 @@ jobs: - name: Build run: echo "Replace with your build command" + + # ── Always applicable, regardless of language ────────────────────────── + # Backstop for the pre-push hook check: catches contributors who never + # activated .githooks. Independent of the placeholder jobs above so it + # keeps working after you replace lint/test/build with real steps. + docs-todo-check: + name: Documentation TODOs + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v6 + + - name: List remaining template placeholders + run: | + TODO_DOCS=$(find docs -name 'todo_*.md' 2>/dev/null || true) + if [ -n "$TODO_DOCS" ]; then + echo "$TODO_DOCS" | while read -r f; do + echo "::warning file=$f::Template placeholder not yet filled in — see docs/README.md" + done + fi + exit 0 From f924b930cc10ca4fd98fe1efaa3bf24a2c610149 Mon Sep 17 00:00:00 2001 From: Mathieu <39670015+mathieusouflis@users.noreply.github.com> Date: Wed, 1 Jul 2026 23:00:57 +0200 Subject: [PATCH 6/9] docs(readme): remove stale FAQ mention from setup comment --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 3e8b30d..ad20a09 100644 --- a/README.md +++ b/README.md @@ -5,9 +5,9 @@ [![CI](https://github.com/your-org/your-repo/actions/workflows/ci.yml/badge.svg)](https://github.com/your-org/your-repo/actions/workflows/ci.yml) From 42ffe03560ad779a6987981eb6704fede81d573a Mon Sep 17 00:00:00 2001 From: Mathieu <39670015+mathieusouflis@users.noreply.github.com> Date: Wed, 1 Jul 2026 23:12:41 +0200 Subject: [PATCH 7/9] docs(contributing): keep procedural content canonical instead of splitting it Commit conventions, bug/feature reporting, and PR process move back into CONTRIBUTING.md and stay there, matching how CODE_OF_CONDUCT.md and SECURITY.md are already treated: content stays at the GitHub-fixed path, the grid links to it rather than absorbing it. GitHub surfaces CONTRIBUTING.md directly when a contributor opens a PR or issue, so splitting it into docs/team-process added a click at exactly the moment someone needs the answer fastest. --- CONTRIBUTING.md | 125 +++++++++++++++++- .../reference/commit-conventions.md | 53 -------- .../reference/pull-request-process.md | 59 --------- 3 files changed, 120 insertions(+), 117 deletions(-) delete mode 100644 docs/team-process/reference/commit-conventions.md delete mode 100644 docs/team-process/reference/pull-request-process.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a209646..ab8d973 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,21 @@ # Contributing -Thank you for your interest in contributing! This document explains how to get involved. Detailed process reference lives in [`docs/team-process/`](docs/team-process/) — this file is the short entry point, not the full spec. +Thank you for your interest in contributing! This document explains how to get involved, what we expect, and how to get your changes merged. + +--- + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [Getting Started](#getting-started) +- [How to Contribute](#how-to-contribute) + - [Reporting Bugs](#reporting-bugs) + - [Suggesting Features](#suggesting-features) + - [Submitting Code Changes](#submitting-code-changes) +- [Commit Conventions](#commit-conventions) +- [Pull Request Process](#pull-request-process) +- [Code Style](#code-style) +- [Testing](#testing) --- @@ -23,17 +38,117 @@ This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT. git remote add upstream https://github.com/your-org/your-repo.git ``` 4. Follow the full setup guide: [docs/product-code/tutorials/getting-started](docs/product-code/tutorials/getting-started.md) -5. Activate the Git hooks (one-time, recommended): [docs/team-process/how-to/activate-git-hooks](docs/team-process/how-to/activate-git-hooks.md) +5. Activate the Git hooks (one-time, recommended — validates commit messages locally before you push): [docs/team-process/how-to/activate-git-hooks](docs/team-process/how-to/activate-git-hooks.md) --- ## How to Contribute -Reporting bugs, suggesting features, submitting code changes, and the review/merge process are all covered in one place: [docs/team-process/reference/pull-request-process](docs/team-process/reference/pull-request-process.md). +### Reporting Bugs + +Before opening an issue: +- Search [existing issues](../../issues) to avoid duplicates +- Make sure you are on the latest version (`git pull upstream main`) + +When opening a bug report, use the **Bug Report** template and include: +- Steps to reproduce +- Expected vs actual behavior +- Your environment (OS, runtime version, relevant tool versions) +- Relevant logs or screenshots + +### Suggesting Features + +Open a **Feature Request** issue with: +- A clear description of the problem the feature solves +- Your proposed solution +- Alternatives you considered + +Features that align with the project's scope and architecture are more likely to be accepted. + +### Submitting Code Changes + +1. Create a branch from `main`: + ```bash + git checkout main + git pull upstream main + git checkout -b feat/your-feature-name + ``` +2. Make your changes following the [code style](#code-style) guidelines +3. Write or update tests +4. Run the validation suite locally (see [Getting Started](docs/product-code/tutorials/getting-started.md)) +5. Commit following [commit conventions](#commit-conventions) +6. Push and open a Pull Request + +--- + +## Commit Conventions + +We follow **Conventional Commits**. Each commit message should be: + +``` +(): + +[optional body] + +[optional footer] +``` + +**Types:** + +| Type | When to use | +|------------|----------------------------------------| +| `feat` | New feature or behavior | +| `fix` | Bug fix | +| `refactor` | Code change with no behavior change | +| `test` | Adding or updating tests | +| `docs` | Documentation only | +| `chore` | Tooling, dependencies, config | +| `perf` | Performance improvement | +| `ci` | CI/CD changes | + +**Scope** (optional): the module or area affected, e.g. `auth`, `api`, `ui`, `docker`. + +**Examples:** +``` +feat(auth): add refresh token revocation on logout +fix(api): return 409 when resource already exists +refactor(core): extract validation to separate utility +test(auth): add unit tests for login use case +docs(setup): add environment variable reference +chore(deps): upgrade dependencies +``` + +**Rules:** +- Use the **imperative mood** ("add" not "adds" or "added") +- Keep the first line under **72 characters** +- Reference issues in the footer: `Closes #42`, `Fixes #17` + +Enforced automatically both locally (if hooks are activated) and in CI — see [docs/operations/concept/ci-cd-pipeline](docs/operations/concept/ci-cd-pipeline.md) for how. + +--- + +## Pull Request Process + +1. **One PR per concern** — don't mix unrelated changes +2. **Fill the PR template** — describe what changed and why +3. **Keep diffs small** — large PRs are hard to review; split if needed. Aim for something reviewable in under 30 minutes +4. **All CI checks must pass** before merging +5. **Address review comments** — don't force-merge, iterate on feedback +6. **Squash or rebase** before merge if history is messy + +PRs are merged by maintainers once they have one approving review and all checks are green — see [docs/organizational/reference/todo_tool-inventory](docs/organizational/reference/todo_tool-inventory.md) / [.github/CODEOWNERS](.github/CODEOWNERS) for who that is on this project. + +--- + +## Code Style + +See [docs/product-code/reference/code-style](docs/product-code/reference/code-style.md) for detailed conventions. + +--- -Commit messages follow Conventional Commits, validated automatically both locally (if hooks are activated) and in CI: [docs/team-process/reference/commit-conventions](docs/team-process/reference/commit-conventions.md). +## Testing -Code should follow this project's conventions: [docs/product-code/reference/code-style](docs/product-code/reference/code-style.md). +Every PR should maintain or improve the existing test coverage. --- diff --git a/docs/team-process/reference/commit-conventions.md b/docs/team-process/reference/commit-conventions.md deleted file mode 100644 index a306796..0000000 --- a/docs/team-process/reference/commit-conventions.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -domain: team-process -type: reference -owner: -last_reviewed: ---- - -# Commit Conventions - -We follow **Conventional Commits**, enforced automatically — see [operations/concept/ci-cd-pipeline](../../operations/concept/ci-cd-pipeline.md) for how. Each commit message should be: - -``` -(): - -[optional body] - -[optional footer] -``` - -**Types:** - -| Type | When to use | -|------------|----------------------------------------| -| `feat` | New feature or behavior | -| `fix` | Bug fix | -| `refactor` | Code change with no behavior change | -| `test` | Adding or updating tests | -| `docs` | Documentation only | -| `chore` | Tooling, dependencies, config | -| `perf` | Performance improvement | -| `ci` | CI/CD changes | - -**Scope** (optional): the module or area affected, e.g. `auth`, `api`, `ui`, `docker`. - -**Examples:** -``` -feat(auth): add refresh token revocation on logout -fix(api): return 409 when resource already exists -refactor(core): extract validation to separate utility -test(auth): add unit tests for login use case -docs(setup): add environment variable reference -chore(deps): upgrade dependencies -``` - -**Rules:** -- Use the **imperative mood** ("add" not "adds" or "added") -- Keep the first line under **72 characters** -- Reference issues in the footer: `Closes #42`, `Fixes #17` - -## See also - -- [team-process/how-to/activate-git-hooks](../how-to/activate-git-hooks.md) -- [operations/concept/ci-cd-pipeline](../../operations/concept/ci-cd-pipeline.md) diff --git a/docs/team-process/reference/pull-request-process.md b/docs/team-process/reference/pull-request-process.md deleted file mode 100644 index a33d23a..0000000 --- a/docs/team-process/reference/pull-request-process.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -domain: team-process -type: reference -owner: -last_reviewed: ---- - -# Pull Request Process - -## Reporting bugs - -Before opening an issue: -- Search [existing issues](../../../../issues) to avoid duplicates -- Make sure you are on the latest version (`git pull upstream main`) - -When opening a bug report, use the **Bug Report** template and include: -- Steps to reproduce -- Expected vs actual behavior -- Your environment (OS, runtime version, relevant tool versions) -- Relevant logs or screenshots - -## Suggesting features - -Open a **Feature Request** issue with: -- A clear description of the problem the feature solves -- Your proposed solution -- Alternatives you considered - -Features that align with the project's scope and architecture are more likely to be accepted. - -## Submitting code changes - -1. Create a branch from `main`: - ```bash - git checkout main - git pull upstream main - git checkout -b feat/your-feature-name - ``` -2. Make your changes following [product-code/reference/code-style](../../product-code/reference/code-style.md) -3. Write or update tests — every PR should maintain or improve existing coverage -4. Run the validation suite locally (see [product-code/tutorials/getting-started](../../product-code/tutorials/getting-started.md)) -5. Commit following [team-process/reference/commit-conventions](commit-conventions.md) -6. Push and open a Pull Request - -## Review and merge - -- **One PR per concern** — don't mix unrelated changes -- **Fill the PR template** — describe what changed and why -- **Keep diffs small** — large PRs are hard to review; split if needed. Aim for something reviewable in under 30 minutes -- **All CI checks must pass** before merging -- **Address review comments** — don't force-merge, iterate on feedback -- **Squash or rebase** before merge if history is messy - -PRs are merged by maintainers once they have one approving review and all checks are green — see [organizational/reference](../../organizational/reference/) for who that is on this project. - -## See also - -- [product-code/reference/code-style](../../product-code/reference/code-style.md) -- [team-process/reference/commit-conventions](commit-conventions.md) From 573969ecbbe5f6aa2ec6acec8f58516accb1b1ab Mon Sep 17 00:00:00 2001 From: Mathieu <39670015+mathieusouflis@users.noreply.github.com> Date: Wed, 1 Jul 2026 23:12:47 +0200 Subject: [PATCH 8/9] docs: fix cross-references after CONTRIBUTING.md consolidation --- docs/README.md | 7 ++++--- docs/operations/concept/ci-cd-pipeline.md | 4 ++-- docs/team-process/how-to/activate-git-hooks.md | 4 ++-- 3 files changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/README.md b/docs/README.md index ae01f9b..c11b3d0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,9 +6,10 @@ Organized by two axes: **domain** (what this document is about) and **type** (wh |---|---|---|---|---|---|---| | **[product-code](product-code/)** | [Architecture overview](product-code/concept/todo_architecture-overview.md) 🚧 | — | [Code style](product-code/reference/code-style.md), [Environment variables](product-code/reference/environment-variables.md) | [First decision](product-code/decisions/todo_first-architecture-decision.md) 🚧 | [Getting started](product-code/tutorials/getting-started.md) | — | | **[operations](operations/)** | [CI/CD pipeline](operations/concept/ci-cd-pipeline.md) | — | — | — | — | [Deployment](operations/runbooks/todo_deployment-runbook.md) 🚧 | -| **[team-process](team-process/)** | — | [Activate Git hooks](team-process/how-to/activate-git-hooks.md) | [Commit conventions](team-process/reference/commit-conventions.md), [PR process](team-process/reference/pull-request-process.md) | — | — | — | -| **[organizational](organizational/)** | [Role charter](organizational/concept/todo_role-charter.md) 🚧 | — | [Tool inventory](organizational/reference/todo_tool-inventory.md) 🚧 | [Tooling choice](organizational/decisions/todo_tooling-choice.md) 🚧 | — | — | +| **[team-process](team-process/)** | — | [Activate Git hooks](team-process/how-to/activate-git-hooks.md) | [Commit conventions & PR process](../CONTRIBUTING.md) ⧉ | — | — | — | +| **[organizational](organizational/)** | [Role charter](organizational/concept/todo_role-charter.md) 🚧 | — | [Tool inventory](organizational/reference/todo_tool-inventory.md) 🚧, [Code owners](../.github/CODEOWNERS) ⧉ | [Tooling choice](organizational/decisions/todo_tooling-choice.md) 🚧 | — | — | 🚧 = template placeholder (`todo_` prefix), no real content yet — see the note inside each file for what to fill in and how to rename it once done. +⧉ = lives outside `docs/` at a fixed path, see below. -A few things intentionally live outside this grid, at fixed paths GitHub itself expects: [`README.md`](../README.md), [`CONTRIBUTING.md`](../CONTRIBUTING.md), [`CODE_OF_CONDUCT.md`](../CODE_OF_CONDUCT.md), [`SECURITY.md`](../SECURITY.md), [`LICENSE`](../LICENSE), and [`.github/CODEOWNERS`](../.github/CODEOWNERS). Moving them would break the platform features tied to those paths (Security tab, community profile checklist, the PR-open banner). Each links into this grid for detail rather than duplicating it. +A few things intentionally live outside this grid, at fixed paths GitHub itself expects: [`README.md`](../README.md), [`CONTRIBUTING.md`](../CONTRIBUTING.md), [`CODE_OF_CONDUCT.md`](../CODE_OF_CONDUCT.md), [`SECURITY.md`](../SECURITY.md), [`LICENSE`](../LICENSE), and [`.github/CODEOWNERS`](../.github/CODEOWNERS). Moving them would break the platform features tied to those paths (Security tab, community profile checklist, the PR-open banner) — so unlike the rest of the grid, these stay canonical at their GitHub-required location, and the grid links *to* them rather than absorbing their content. `CONTRIBUTING.md` in particular is intentionally kept complete (commit conventions, bug/feature reporting, PR process included inline) rather than split into `docs/team-process/`, since GitHub surfaces it directly at the moment a contributor opens a PR or issue — splitting it would add a click at exactly the point someone needs the answer fastest. diff --git a/docs/operations/concept/ci-cd-pipeline.md b/docs/operations/concept/ci-cd-pipeline.md index 3efc970..97e330f 100644 --- a/docs/operations/concept/ci-cd-pipeline.md +++ b/docs/operations/concept/ci-cd-pipeline.md @@ -28,7 +28,7 @@ Commit messages are validated against Conventional Commits **twice**, both reusi - **Locally**, if the contributor activated the hook (`git config core.hooksPath .githooks`) — fast feedback, but optional and easy to skip. - **In CI**, on every pull request — the `commitlint.yml` workflow re-runs the same script against every commit in the PR, so a contributor who never activated the local hook is still caught before merge. -See [team-process/reference/commit-conventions](../../team-process/reference/commit-conventions.md) for the rule itself. +See [Commit Conventions](../../../CONTRIBUTING.md#commit-conventions) for the rule itself. ## Release — `.github/workflows/release.yml` @@ -40,6 +40,6 @@ Two ecosystems are always active regardless of language: `github-actions` (workf ## See also -- [team-process/reference/commit-conventions](../../team-process/reference/commit-conventions.md) +- [Commit Conventions](../../../CONTRIBUTING.md#commit-conventions) - [team-process/how-to/activate-git-hooks](../../team-process/how-to/activate-git-hooks.md) - [operations/runbooks](../runbooks/) diff --git a/docs/team-process/how-to/activate-git-hooks.md b/docs/team-process/how-to/activate-git-hooks.md index d1d2ec3..b28fdf5 100644 --- a/docs/team-process/how-to/activate-git-hooks.md +++ b/docs/team-process/how-to/activate-git-hooks.md @@ -23,7 +23,7 @@ This repo ships two shell-based hooks under `.githooks/` — no runtime or depen | Hook | Runs on | Purpose | |---|---|---| -| `commit-msg` | every `git commit` | Rejects commit messages that don't follow [Conventional Commits](../reference/commit-conventions.md) | +| `commit-msg` | every `git commit` | Rejects commit messages that don't follow [Conventional Commits](../../../CONTRIBUTING.md#commit-conventions) | | `pre-push` | every `git push` | Placeholder — uncomment the test/build checks inside `.githooks/pre-push` to run them before every push | ## Why this is optional but recommended @@ -32,5 +32,5 @@ Activating the hook is not required to contribute — `commit-msg` validation al ## See also -- [team-process/reference/commit-conventions](../reference/commit-conventions.md) +- [Commit Conventions](../../../CONTRIBUTING.md#commit-conventions) - [operations/concept/ci-cd-pipeline](../../operations/concept/ci-cd-pipeline.md) From 92145b8befaeb1476fb7953f7360750c0cec6db3 Mon Sep 17 00:00:00 2001 From: Mathieu <39670015+mathieusouflis@users.noreply.github.com> Date: Wed, 1 Jul 2026 23:28:04 +0200 Subject: [PATCH 9/9] docs(readme): remove dead Development anchor, add missing Documentation entry The Development section's placeholder commands were pure duplication of docs/product-code/tutorials/getting-started.md's Common Commands section and were correctly dropped during the restructure, but the Table of Contents still linked to it. Also add the Documentation section, which existed but was never listed. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ad20a09..8cb57bd 100644 --- a/README.md +++ b/README.md @@ -21,8 +21,8 @@ One-paragraph description of what this project does and who it is for. - [Overview](#overview) - [Getting Started](#getting-started) -- [Development](#development) - [Architecture](#architecture) +- [Documentation](#documentation) - [Contributing](#contributing) - [License](#license)