Skip to content

Contributing

Conventions

Max line length 90 (see .editorconfig), 119 for HTML, JS and CSS files. Check with:

{ git ls-files | grep -vE '^(scripts/nanocode\.sh|README\.md|assets/|site/)';
  git ls-files | grep -E '^site/.*\.(html|js|css)$'; } \
  | xargs awk 'length > (FILENAME ~ /\.(html|js|css)$/ ? 119 : 90) \
      {print FILENAME":"FNR" len="length}'

Exempt, because they cannot wrap cleanly or are generated: scripts/nanocode.sh (a verbatim copy), README.md (badge tables), assets/ (SVG brand files are single-line by nature), site/ (the landing's long single-line data strings — its HTML/JS/CSS are still checked, at 119), and generated files such as site/package-lock.json.

House rules that keep the stack predictable:

  • Every service is a compose profile named after the service. If you add one, add it to OPT_SERVICES in setup.sh too — the chooser and the profiles must stay in sync.
  • Nothing is published publicly by default. New services bind 127.0.0.1 unless there is a reason not to, and reachability comes from cloudflared via its config.template.yml.
  • Secrets never go on argv or in git. .env and the rendered config/cloudflared/config.yml are gitignored; the template is the source of truth.
  • Named volumes hold runtime state, not image content — see Storage for why that distinction matters.

Building the site and docs

The landing (site/) and the docs (docs/) build separately but deploy together (docs land under /docs/ of the same site):

# landing — needs the theme submodule checked out (site/src/theme)
cd site && npm ci && npm run build

# docs — build the landing first, docs land in site/dist/docs
python3 -m pip install -r mkdocs/requirements.txt
python3 -m mkdocs build --strict -f mkdocs.yml

CI runs both on every merge request (validate) and publishes on the default branch (pages).

Changes to setup.sh

Use the dry run before claiming anything works:

sudo ./setup.sh --dry-run

It is idempotent by design — re-running must never destroy volumes or workspaces. Keep it that way.

License

MIT — see LICENSE. By contributing you agree your changes are released under it.