Commit 83772022 authored by Pierre Smeyers's avatar Pierre Smeyers
Browse files

build: add CLAUDE context

parent 28cbb434

.claude/CLAUDE.md

0 → 100644
+35 −0
Original line number Diff line number Diff line 
# Global Claude Code Rules



This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.



## AI Agent Instructions



- Never assume or guess when a request is ambiguous or lacks detail

- Ask one targeted clarifying question before proceeding

- Be concise and to the point

- Avoid filler phrases, redundant explanations, and unnecessary elaboration

- Only elaborate when the user explicitly asks for more detail



## Project Overview



This is a **GitLab CI/CD template** for [Flux CD](https://fluxcd.io/).

It is part of the [to-be-continuous](https://gitlab.com/to-be-continuous) project (TBC).



## Repository Structure



- `README.md` - the user documentation, included in TBC's website that documents all template jobs, features, configuration input/variables and code examples

- `templates/gitlab-ci-xxx.yml` - the main GitLab CI/CD template

- optionally one or several `templates/gitlab-ci-xxx-yyy.yml` - template variants, each providing additional features

- `kicker.json` - a JSON descriptor used by Kicker (an interactive TBC configurer) that declares all template jobs, features and configuration variables

- `logo.png` - the template logo

- `LICENSE` - the license file

- `CHANGELOG.md`

- `CONTRIBUTING.md` - Contributors guide

- `DCO.txt` - Developer Certificate of Origin



## Rules



Detailed rules are in `~/.claude/rules/`:

- `tbc-template-design.md` — architectural principles, naming, design rules, common features, reports

- `tbc-shell.md` — shell scripting portability (Bash/Ash)

- `tbc-git-workflow.md` — commit conventions, DCO, contribution workflow

.claude/rules/tbc-git-workflow.md

0 → 100644
+40 −0
Original line number Diff line number Diff line 
# TBC Git & Contribution Workflow



## License

- LGPL v3. All contributions subject to the Developer Certificate of Origin (DCO).



## Contribution Workflow

- Contributions via **merge requests from forks** on GitLab.

- Releases are automated via **semantic-release** on the `main` branch.



## Git Commit Conventions



Commits must be **atomic** (one logical change) and **semantic** (semantic-release format).



### Format

```

<type>(<scope>): <subject>



<body>



<footer>

```



### Types



| Type | Description | Release |

|------|-------------|---------|

| `feat` | A new feature | minor |

| `fix` | A bug fix | patch |

| `docs` | Documentation only | none |

| `style` | Formatting, no code change | none |

| `refactor` | Neither fix nor feature | none |

| `perf` | Performance improvement | none |

| `test` | Adding/correcting tests | none |

| `chore` | Build process, CI/CD, tooling | none |



### Rules

- **Subject**: imperative present tense, no capitalization, no trailing dot.

- **Max 100 chars** per line in commit messages.

- **Breaking changes**: add `BREAKING CHANGE:` line(s) in the footer.

- **DCO sign-off required**: use `git commit -s`.

.claude/rules/tbc-shell.md

0 → 100644
+48 −0
Original line number Diff line number Diff line 
# TBC Shell Scripting Rules



Shell scripts embedded in YAML `script:` blocks must be portable across Bash and Alpine Ash.



## Required Shell Options

- Always use `set -e` and `set -o pipefail`.



## Bash/Ash Compatibility



**Do NOT use** (Bash-only, not supported in Ash):

- Arrays and dictionaries

- `declare`

- Arithmetic commands `(( ))`

- Here-strings `<<<`

- Indirect expansion `${!var}`

- Case-changing expansion `${var^^}`, `${var,,}`

- Replace prefix/suffix expansion `${var/#pat/rep}`, `${var/%pat/rep}`

- Operator expansion `${var@u}`, `${var@U}`, `${var@L}`



**Safe to use** (supported in both Bash and Ash):

- Conditionals `[[ ]]`, regex `=~` (but not `$BASH_REMATCH`)

- Parameter expansion: `${var:-default}`, `${var:+word}`, `${var#prefix}`, `${var##prefix}`, `${var%suffix}`, `${var%%suffix}`, `${var/pat/rep}`, `${var//pat/rep}`, `${#var}`

- Substring expansion `${var:offset:length}`

- `local` variables

- Arithmetic expansion `$(( ))`

- Here documents

- Process substitution



## Pitfalls



### Use `awk` instead of `grep` for filtering

`grep` returns non-zero on no match, which breaks `set -e`. Use `awk` instead:

```bash

# BAD: will exit if no match

titles=$(grep ^# README.md)

# GOOD: returns empty string on no match

titles=$(awk '/^#/' README.md)

```

`grep` is acceptable only when its return code is explicitly tested (e.g. in an `if` condition).



### Never use glob patterns for string matching

Alpine Ash conflates glob patterns with filename expansion. Use regex `=~` instead:

```bash

# BAD: breaks on Alpine if a file matches the glob

[[ "test" == "te"* ]]

# GOOD: works everywhere

[[ "test" =~ ^"te" ]]

```

.claude/rules/tbc-template-design.md

0 → 100644
+38 −0
Original line number Diff line number Diff line 
# TBC Template Design Rules



## Template Structure

- Templates use GitLab CI **component input system** (`spec:inputs`) as the primary configuration mechanism, with `variables` as fallback for `include:project`/`include:remote`.

- Every template defines a hidden **base job** (`.xxx-base`) extended by all other jobs. It sets the default image, services, and cache.

- Templates must **not** use nested includes.

- Templates must reuse the standard TBC stages: `build`, `test`, `package-build`, `package-test`, `infra`, `deploy`, `acceptance`, `publish`, `infra-prod`, `production`.



## Naming Conventions

- **Job names**: kebab-case, prefixed with a short template prefix (max 5 chars). E.g. `docker-build`, `mvn-test`.

- **Global variables**: SCREAMING_SNAKE_CASE, prefixed with template/tool name. E.g. `DOCKER_BUILD_ARGS`.

- **Local/dynamic variables**: snake_case. E.g. `environment_url`.



## Design Rules

- **Make everything overridable**: images, CLI arguments, and features must be configurable via variables/inputs.

- **Sensible defaults**: prefer options that raise the bar (quality/security) over conservative ones. Use `latest` image tag for DevSecOps tools; expect users to pin versions for build tools.

- **GitLab by default**: when a feature requires an external service (registry, etc.), configure GitLab's built-in service by default.

- **Fully qualified image names**: always include the registry in image references (e.g. `docker.io/library/docker:latest`) to prevent supply chain attacks.

- **No `parallel:matrix` in templates**: use job prototypes with explicit extends instead, to preserve user multi-instantiation ability.

- **Command-line options**: separate template-controlled options (hard-coded, enforced) from user-controlled options (documented, customizable via variables).



## Common Features (every template must support)

- Proxy configuration (`http_proxy`, `https_proxy`, `no_proxy`)

- Custom CA certificates (`CUSTOM_CA_CERTS`)

- Scoped variables (double-underscore syntax)

- Debug logging (`$TRACE`)

- Configurable Git references (`PROD_REF`, `INTEG_REF`, `RELEASE_REF`)

- Merge Request workflow (default) with adaptive pipeline strategy

- Secrets management with `@b64@` and `@url@` prefixes



## Reports

- Always produce human-readable output in the console.

- When available, produce GitLab-supported report format artifacts.

- Report file path convention: `reports/<job_name>.<format_name>.<extension>`.

- Dotenv artifacts for propagating dynamic variables downstream.



## Multi-instantiation

- Output artifacts (files and dotenv variables) must be namespaced to avoid collisions when a template is multi-instantiated.