SUSTAINABILITY.md

A practical, open format for documenting sustainability commitments, engineering guardrails, and measurable progress.

Think of SUSTAINABILITY.md as a README for digital sustainability — a predictable place where contributors, maintainers, and AI agents can find your standards.

Start with the Template View on GitHub

Why SUSTAINABILITY.md?

Most repositories have README, SECURITY, and CONTRIBUTING files. SUSTAINABILITY.md fills an important gap: it states how your project reduces digital waste, handles trade-offs, and enforces sustainability in daily work.

Why teams adopt it

  • It creates a clear public commitment that users and contributors can see.
  • It helps maintainers align product, engineering, accessibility, and DevOps.
  • It gives AI coding agents explicit constraints before they generate changes.
  • It turns vague goals into measurable implementation steps.

What makes this effective

  • Visible policy: one predictable file in the repo root.
  • Operational ownership: named owners, targets, and review cadence.
  • CI enforcement: checks that prevent regression, not just aspirational text.
  • Continuous improvement: a ratchet model that gets stricter over time.

Start in under 30 minutes

  1. Copy the template.
  2. Add project scope, owner, and 3-5 baseline metrics.
  3. Link your SUSTAINABILITY.md from README.
  4. Enable CI gates for accessibility + performance budgets + Lighthouse.
  5. Schedule a monthly review and raise one threshold.

Status: Draft (work in progress).

AI disclosure: This project has been developed with AI-assisted drafting and implementation support, with human review and editing.

Adopt this now, keep it lightweight, and iterate. Progress over perfection.

The Framework

Shared Commitment

Make sustainability explicit in your repo so every contributor understands expectations before shipping code.

Measurable Operations

Define budgets, owners, and review cadence so sustainability becomes trackable work, not an abstract aspiration.

Guardrails in CI

Automate checks for accessibility, performance budgets, and risky additions to prevent regressions at merge time.

Reference Examples

How to Adopt

1. Publish a starter commitment

Add a short SUSTAINABILITY.md with goals, ownership, and non-negotiable CI gates.

2. Add required CI checks

Gate pull requests with accessibility checks, Lighthouse scans, and budget regression checks.

3. Adopt the full template

Add governance, exception handling, metrics baselines, and monthly review process.

4. Ratchet over time

Raise thresholds progressively as your project stabilizes and contributors build confidence.