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/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 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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fcc0a0c..ab8d973 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,11 +8,9 @@ Thank you for your interest in contributing! This document explains how to get i - [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) @@ -39,13 +37,8 @@ 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 — validates commit messages locally before you push): [docs/team-process/how-to/activate-git-hooks](docs/team-process/how-to/activate-git-hooks.md) --- @@ -72,16 +65,6 @@ Open a **Feature Request** issue with: 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`: @@ -92,7 +75,7 @@ Commit messages are also validated in CI on every PR via GitHub Actions. ``` 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)) +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 @@ -113,7 +96,7 @@ We follow **Conventional Commits**. Each commit message should be: **Types:** | Type | When to use | -|------------|---------------------------------------| +|------------|----------------------------------------| | `feat` | New feature or behavior | | `fix` | Bug fix | | `refactor` | Code change with no behavior change | @@ -140,24 +123,26 @@ chore(deps): upgrade dependencies - 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 +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 push force-merges; iterate on feedback +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. +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 [Code Style Guide](docs/developer-guide/guidelines/code-style.md) for detailed conventions. +See [docs/product-code/reference/code-style](docs/product-code/reference/code-style.md) for detailed conventions. --- @@ -169,4 +154,4 @@ Every PR should maintain or improve the existing test coverage. ## 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..8cb57bd 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) @@ -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) @@ -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. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..c11b3d0 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,15 @@ +# 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 & 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) — 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/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/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). diff --git a/docs/operations/concept/ci-cd-pipeline.md b/docs/operations/concept/ci-cd-pipeline.md new file mode 100644 index 0000000..97e330f --- /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 [Commit Conventions](../../../CONTRIBUTING.md#commit-conventions) 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 + +- [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/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/developer-guide/guidelines/code-style.md b/docs/product-code/reference/code-style.md similarity index 84% rename from docs/developer-guide/guidelines/code-style.md rename to docs/product-code/reference/code-style.md index 7153700..6969b65 100644 --- a/docs/developer-guide/guidelines/code-style.md +++ b/docs/product-code/reference/code-style.md @@ -1,3 +1,10 @@ +--- +domain: product-code +type: reference +owner: +last_reviewed: +--- + # Code Style Guide @@ -15,7 +22,7 @@ This document defines the code style and formatting conventions for this project # Auto-fix formatting ``` -All checks must pass before a PR can be merged. The CI pipeline enforces this automatically. +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). --- @@ -93,3 +100,8 @@ Separate each group with a blank line. ``` 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..b28fdf5 --- /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](../../../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 + +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 + +- [Commit Conventions](../../../CONTRIBUTING.md#commit-conventions) +- [operations/concept/ci-cd-pipeline](../../operations/concept/ci-cd-pipeline.md)