Fix review issues: front matter, headings, consistency, typos
All checks were successful
check / check (push) Successful in 9s

- Move title and last_modified to YAML front matter (all policy docs)
- Make all document sections H1, subsections H2
- Update version rule to reference front matter format
- Fix "our" → "your" typo in Go styleguide
- Fix Python styleguide numbering (2. → 1.)
- Fix README: "flat collection" → accurate description, remove stale TODO
- Remove Makefile items from code styleguides (repo stuff, not code),
  add note linking to Repository Policies
- Change zerolog → slog in Go styleguide
- Fix JS styleguide npm reference: both work, but use make targets
- Drop .json from healthcheck path, add JSON content-type requirement
- Add Author/License to Go HTTP Server Conventions
- Convert hyperlinks to backtick URLs in checklists for consistency
- Add version/front matter to both checklists
This commit is contained in:
2026-02-22 17:15:06 +01:00
parent 3768b8ca02
commit e97b48eea4
9 changed files with 184 additions and 173 deletions

View File

@@ -1,19 +1,13 @@
Version: 2026-02-22
---
title: Code Styleguide
last_modified: 2026-02-22
---
# Code Styleguide
# All
## All
1. Every project/repo should have a `Makefile` in the root. At a minimum,
`make clean`, `make run`, `make fmt`, and `make test` should work. Choose a
sane default target (`test` for libraries, `run` or `publish` for binaries).
`fmt` should invoke the appropriate formatters for the files in the repo,
such as `go fmt`, `prettier`, `black`, etc. Other standard `Makefile` targets
include `deploy`, `lint`. Consider the `Makefile` the official documentation
about how to operate the repository.
1. If it's possible to write a `Dockerfile`, include at least a simple one. It
should be possible to build and run the project with `docker build .`.
1. Every repo must have a `Makefile` and a `Dockerfile`. See
[Repository Policies](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md)
for required targets and conventions.
1. For F/OSS-licensed software, try to include the full source code of the
current version (and any dependencies, such as vendored dependencies) in the
@@ -42,18 +36,16 @@ Version: 2026-02-22
be enabled in prod.
1. For services/servers, make a healthcheck available at
`/.well-known/healthcheck`. This is out of spec but it is my personal
standard. This should return a 200 OK if the service is healthy, along with a
JSON object containing the service's name, uptime, and any other relevant
information, and a key of "status" with a value of "ok" if the service is
healthy. Make sure that in the event of a failure, the service returns a 5xx
status code for that route.
`/.well-known/healthcheck`. The response must have a
`Content-Type: application/json` header and return a JSON object containing
the service's name, uptime, and a key of `"status"` with a value of `"ok"`.
Return a 200 for healthy, 5xx for unhealthy.
1. If possible, for services/servers, include a /metrics endpoint that returns
Prometheus-formatted metrics. This is not required for all services, but is a
nice-to-have.
## Bash / Shell
# Bash / Shell
1. Use `[[` instead of `[` for conditionals. It's a shell builtin and doesn't
have to execute a separate process.
@@ -73,7 +65,7 @@ Version: 2026-02-22
1. Put all code in functions, even a main function. Define all functions then
call main at the bottom of the file.
## Docker Containers (for services)
# Docker Containers (for services)
1. Use `runit` with `runsvinit` as the entrypoint for all containers. This
allows for easy service management and logging. In startup scripts