Add agent notes, coding standards, and the issue tracker
This commit is contained in:
tanshu committed
1 parent
4ddeba5402
commit
a9ac51bd43
4 files changed
+142
-8
No files matched your search
@@ -0,0 +1,16 @@
|
||||
# Agent notes
|
||||
|
||||
This repository holds one Ansible playbook per service. Read
|
||||
[CODING_STANDARDS.md](CODING_STANDARDS.md) before adding or changing a playbook.
|
||||
|
||||
- Layout and naming: [CODING_STANDARDS.md](CODING_STANDARDS.md).
|
||||
- Checks: run `./scripts/check.sh`. It runs yamllint, ansible-lint, and a syntax
|
||||
check on every `*/playbook.yml`. CI runs the same script.
|
||||
- Review baseline: `origin/main`. The review diff is `git diff origin/main...HEAD`.
|
||||
- Migration spec: [docs/podman-migration.md](docs/podman-migration.md). Section 8
|
||||
lists the repo changes the migration expects.
|
||||
- Issue tracker: [docs/agents/issue-tracker.md](docs/agents/issue-tracker.md).
|
||||
- Scratch files: write them under `.scratch/`. It is git-ignored, and `/tmp` is
|
||||
wiped between tool calls in this environment.
|
||||
- Secrets: `vars/default.yml` holds deploy values, including passwords. Do not
|
||||
copy a production value into a file you push to a public remote.
|
||||
@@ -0,0 +1,80 @@
|
||||
# Coding standards
|
||||
|
||||
Rules a reviewer applies to a diff. Anything a tool can check lives in
|
||||
`.yamllint`, `.ansible-lint`, or `scripts/check.sh`. This file covers the calls a
|
||||
tool cannot make.
|
||||
|
||||
## Layout
|
||||
|
||||
A service directory is either flat or role-based. Pick by the service, not by
|
||||
taste.
|
||||
|
||||
Use the flat layout for one container plus a proxy:
|
||||
|
||||
```
|
||||
service/
|
||||
├── files/
|
||||
├── vars/
|
||||
│ └── default.yml
|
||||
├── playbook.yml
|
||||
└── readme.md
|
||||
```
|
||||
|
||||
Use roles when the service has more than one container, unit, or stateful volume:
|
||||
|
||||
```
|
||||
service/
|
||||
├── roles/
|
||||
│ ├── network/
|
||||
│ ├── storage/
|
||||
│ └── service/
|
||||
├── vars/
|
||||
│ └── default.yml
|
||||
├── playbook.yml
|
||||
└── readme.md
|
||||
```
|
||||
|
||||
`playbook.yml` lists roles in dependency order. The data tier goes first, the app
|
||||
next, and the edge last. Each role has `tasks/main.yaml`. Add
|
||||
`handlers/main.yaml` and `templates/` only when the role needs them.
|
||||
|
||||
## Naming
|
||||
|
||||
- `playbook.yml`, `vars/default.yml`, and `readme.md` in every service directory.
|
||||
- Role task and handler files use `main.yaml`. Playbook and vars files use `.yml`.
|
||||
This matches the existing tree. Do not rename either set in an unrelated change.
|
||||
- Handler names describe the action, for example "Restart Caddy", not the trigger.
|
||||
|
||||
## YAML
|
||||
|
||||
- Two-space indent, no tabs, LF line endings.
|
||||
- Quote Jinja values only when YAML would misread them.
|
||||
- Task names are sentence case and specific. "Create the data directory" is
|
||||
better than "Create directory".
|
||||
|
||||
## Tasks
|
||||
|
||||
- Prefer a module to `command` or `shell`. When a command is necessary, add
|
||||
`creates`, `changed_when`, or `failed_when` so a second run reports no change.
|
||||
- Put a long command string in `files/` or a template.
|
||||
- A task that writes a config file notifies a handler. It does not restart the
|
||||
container inline.
|
||||
- Do not add `ignore_errors` to silence a check. Fix the task or narrow it.
|
||||
|
||||
## Variables
|
||||
|
||||
- Every variable a playbook needs has a value in `vars/default.yml` or a comment
|
||||
naming the host fact that supplies it.
|
||||
- Quote passwords so a leading `0` or a `#` survives YAML.
|
||||
- `vars/default.yml` is where this repo keeps deploy values, including passwords.
|
||||
Treat that file as sensitive. Rotate any value that leaks.
|
||||
|
||||
## README
|
||||
|
||||
Each `readme.md` states what the playbook deploys, the variables the operator
|
||||
must set, and the command to run it. Link the upstream image or project.
|
||||
|
||||
## Commits
|
||||
|
||||
One logical change per commit. Sentence case, imperative. Reference the issue
|
||||
when there is one, for example `Closes #12`.
|
||||
@@ -13,14 +13,12 @@ _\*the Initial Server Setup should be your starting point for fresh servers._
|
||||
|
||||
## Playbook Structure
|
||||
|
||||
The playbooks contained in this repository were created for educational purposes, and should serve as a base for you to create your own playbooks and roles.
|
||||
Each service gets its own directory. A single-container service uses the flat layout below. A service with more than one container, unit, or stateful volume uses `roles/`. [CODING_STANDARDS.md](CODING_STANDARDS.md) states the rule and the naming conventions.
|
||||
|
||||
Although we opt to not use roles, our playbooks follow a distinctive structure to facilitate reuse while keeping them mostly self-contained and straightforward.
|
||||
|
||||
For instance, this is how the `lemp` playbook is structured:
|
||||
For instance, this is the flat layout:
|
||||
|
||||
```
|
||||
lemp_ubuntu1804
|
||||
service
|
||||
├── files
|
||||
│ ├── info.php.j2
|
||||
│ └── nginx.conf.j2
|
||||
@@ -31,10 +29,10 @@ lemp_ubuntu1804
|
||||
```
|
||||
|
||||
|
||||
- `files/`: directory containing templates and other files required by the playbook.
|
||||
- `vars/`: directory to save variable files. A `default.yml` var file is included by default.
|
||||
- `files/`: templates and static files the playbook copies or templates.
|
||||
- `vars/`: variable files. `default.yml` holds the values the operator sets.
|
||||
- `playbook.yml`: the playbook file.
|
||||
- `readme.md`: instructions and links related to this playbook.
|
||||
- `readme.md`: what the playbook deploys, the variables to set, and the command to run it.
|
||||
|
||||
## Getting Started
|
||||
|
||||
|
||||
@@ -0,0 +1,40 @@
|
||||
# Issue tracker
|
||||
|
||||
The tracker is the Gitea instance at https://git.tanshu.com/tanshu/playbooks.
|
||||
Issues live under the Issues tab of that repository.
|
||||
|
||||
## Fetching an issue
|
||||
|
||||
Set a token once. Create one at https://git.tanshu.com/user/settings/applications
|
||||
with the `read:issue` scope.
|
||||
|
||||
export GITEA_TOKEN=...
|
||||
|
||||
Then read one issue and its comments:
|
||||
|
||||
curl -s -H "Authorization: token $GITEA_TOKEN" \
|
||||
https://git.tanshu.com/api/v1/repos/tanshu/playbooks/issues/123
|
||||
|
||||
curl -s -H "Authorization: token $GITEA_TOKEN" \
|
||||
https://git.tanshu.com/api/v1/repos/tanshu/playbooks/issues/123/comments
|
||||
|
||||
The JSON carries `title` and `body`. Pass those to the spec reviewer.
|
||||
|
||||
## Finding the issue for a change
|
||||
|
||||
Commit messages reference issues as `#123`. Check the commits under review:
|
||||
|
||||
git log --oneline origin/main..HEAD
|
||||
|
||||
If no message references an issue, ask the user for the issue number. Do not
|
||||
guess.
|
||||
|
||||
## Specs without an issue
|
||||
|
||||
Larger changes use a plan in `docs/` instead of an issue. The Podman migration
|
||||
plan is `docs/podman-migration.md`. Section 8 lists the repo changes it expects.
|
||||
|
||||
## Private or missing tracker
|
||||
|
||||
If the host is unreachable or the token is absent, say so and fall back to a spec
|
||||
file under `docs/`. Do not invent requirements.
|
||||
Reference in new issue
Block a user