Contribution guidelines¶
Thank you for considering to help this project.
Project architecture¶
See Project architecture for how the workspace and its tooling are organized.
Development¶
To run an audit without contributing to the workspace, use installation and your first audit. The commands here also install documentation, lint and development tooling.
Installation¶
Requirements:
uv, Node.js and npm (use the version in.node-version), just, prek, lychee
Clone the repository, configure the git hooks, then initialize with just init.
git clone git@github.com:thibaudcolas/web-sustainability-agents.git
cd web-sustainability-agents/
# Install everything.
just init
Initialization installs Python and npm dependencies and downloads the pinned Vale binary for prose checks. This first run requires network access; the checked-in Vale rules need no separate style download.
Commands¶
just help: See what commands are available.just init: Install dependencies and initialize for development.just lint: Lint the project.just lint-prose: Check prose terminology and common American English spellings with Vale.just format *paths=".": Format project files.just check-links: Check local links without network access.just check-external-links: Check HTTP(S) sources separately.just build-docs: Build the documentation.just test: Test agent skill publishing, documentation rendering, browser collection, ratings, and the benchmark grader.just audit-install: Install the pinned Playwright Chromium browser used by audit tests.just audit-sites: Run the Python staged collector, footprint-document discovery, and Wappalyzer; publish sanitized evidence.just audit-reports: Export per-site report JSON and CSV from existing evidence; see the reporting contract.uv run --locked --script audit/workflow.py init|collect|score: Create a per-origin plan, run collectors, and score agent reviews; see the agent workflow.just audit-review-packets: Prepare bounded evidence packets for the audit skills; reviewers produce judgments, not aggregate scores.just audit-assess: Recalculate scoped scores, annual footprint scenarios and report exports from published evidence/reviews. This does not call models or recollect sites.just audit-scope: Collect broader metadata/preference/recovery observations and generate per-site guideline registers.just audit-energy: Run the supplied co2-runner adapter; keep tests and model campaigns separate from hardware measurement.just audit-traffic: Retrieve the latest public CrUX mirror and derive scoped traffic scenarios; see the energy and traffic experiment.just benchmark-expanded-build: Freeze 12 evidence-review tasks; model commands and interpretation are in the expanded benchmark. Do not rebuild during a campaign.just benchmark-breadth-build: Freeze sixteen broader interpretation and collection-handoff cases; see the broader benchmark.just benchmark-scope-build: Freeze nineteen scope and qualitative review cases; see the scope benchmark.just benchmark-methodology-build: Freeze ten additional scoring, estimation and skill-review cases; see the methodology benchmark. Builders reject nonempty task directories.just benchmark-build: Build Harbor development tasks from frozen fixture observations.just benchmark-controls: Run the reference and no-operation agents through Harbor.just benchmark-neuralwatt/just benchmark-codex: Run the bounded model campaigns; see the executable slice for authentication and interpretation.just docs: Build the documentation and serve it locally.
Coding style & conventions¶
We follow PEP 8 for Python code style, enforced automatically by ruff:
- Python: formatted with
ruff format, linted withruff check. Configuration inpyproject.toml. - Audit and automation scripts: use Python with uv. Standalone entry points must be executable, start with
#!/usr/bin/env -S uv run --script, and declare Python requirements, pinned dependencies, andtool.uv.required-versionin PEP 723 inline metadata. Commit theiruv lock --scriptlockfiles and verify withuv run --locked --script. Keep ordinary imported modules separate from executable entry points. Historical JavaScript experiments remain reproducible; new orchestration uses Python. The pinned CO2.js adapter is retained as a narrow library bridge rather than duplicating SWDM formulas. - Other files: formatted with
prettier(seeprettier.config.js). - Indentation: 4 spaces, no tabs.
- Type annotations: required on all production code, checked by
mypywith strict settings and byty(experimental). - Naming:
snake_casefor functions, methods, and variables;PascalCasefor classes;UPPER_CASEfor constants. Test modules followtest_*.py, test functionstest_*, test classesTest*. - Imports: organized automatically by
ruff(isort rules inpyproject.toml). - Error handling: use specific exception types; avoid bare
except:clauses (BLE rules). - Comments: avoid hard-wrapping lines, except at full stops, or other punctuation like commas if must be.
Documentation¶
Good documentation helps users and contributors understand the project without reading source code. We aim for docs that are accurate, discoverable, and maintainable.
For prose style, tone, terminology, headings, and linking conventions, follow the documentation style guide.
Prose documentation¶
- User-facing docs live in
docs/; the README is the entry point. - Track writing and review dates in git, not manual page datelines. Keep source-version dates and measurement timestamps when they are part of the evidence.
- Cite reference projects through canonical public sources, not checkout paths. Use verified commit permalinks for version-specific claims; see source linking guidance.
- Keep language concise and in Sentence case (no Title Case).
- Follow the documentation style guide for tone, terminology, headings, and linking conventions.
- Run
just formatbefore committing so prettier formats Markdown files consistently.
MkDocs configuration¶
The documentation site is built with MkDocs from the Markdown files in docs/, configured in mkdocs.yml. When you add, rename, or move pages, keep the configuration in sync with the file structure:
- Landing pages: each section folder uses a
README.mdas its landing page, so it also renders when browsing the folder on GitHub. - Navigation: the
navkey should list all pages of the site. - llms.txt: the
llmstxtplugin'ssectionskey lists the pages included in the generatedllms-full.txt. Add new section landing pages there as well.
mkdocs.yml documents each option with an inline comment. The Markdown-facing syntax for features such as code annotations, tabbed blocks, or page tags is documented in the documentation style guide; the build-time behavior of each plugin is described in Project architecture.
Every docs page must be listed in nav, or explicitly opted out:
- Working drafts are published like any other page, with a draft-status callout at the top (see the style guide).
- Files that aren't pages (snippet sources like
contributing/abbreviations.md) are listed inexclude_docs. - Pages intentionally published outside
navmust match the top-levelnot_in_navsetting inmkdocs.yml, which accepts file patterns relative todocs/:
This only suppresses navigation warnings; the page remains published and searchable. Use the search controls to adjust search separately.
Run just build-docs to check your changes – it builds with --strict, so missing nav entries, unresolved links, and broken anchors fail the build.
Pull request workflow¶
- Create a branch from
mainwith a descriptive name. - Make your changes, following the coding style and testing guidelines above.
- Run
just lint,just check-links,just build-docs, andjust testlocally. Runjust check-external-linkswhen adding or updating sources. - Open a pull request with a clear description of what the change does and why. Include relevant test evidence (commands and their output) and links to related issues.
- CI runs linting (ruff, mypy, ty, prettier, Vale), local link checking, tests, and a strict documentation build. External links run in a separate workflow; investigate failures as broken or unverified sources. That workflow also runs weekly and does not gate deployment.
- Squash merge when approved. Keep the commit message concise, in the imperative mood, and using Sentence case (no Title Case).
Support guidelines¶
Static typing¶
All project code should pass static type checking by mypy, with as strict of a configuration as possible, and tentatively also pass type checks with the ty checker.