Contributing to the MIME TODO Specification

This document covers how to maintain the MIME TODO specification repository: building, deploying, and managing URLs.

Prerequisites

All build and publish commands run inside a pipenv environment. Install dependencies first:

pipenv install

Building

HTML

pipenv run make build/html

Output: build/html/

Markdown (agent-consumable)

pipenv run make dist/markdown

Output: dist/markdown/

Both + publish

pipenv run make all

Publishing

The specification is served from specs.code.tiararodney.com. The publish Makefile recipe deploys both build/html and dist/markdown via rsync:

pipenv run make publish

This uploads to:

root@tiararodney.com:/root/webserver/srv/http/spec.tiararodney.com/mime-todo

The resulting web structure is:

https://specs.code.tiararodney.com/mime-todo/
├── html/          ← HTML output
└── markdown/      ← Markdown output (agent-consumable)
    ├── README.md  ← The specification
    └── AGENTS.md  ← Agent consumption instructions

URL Management

The following files contain URLs pointing to the web server. If the server address, path structure, or spec name changes, update these:

AGENTS.md — the "Consuming the Specification" section lists direct URLs

If this spec is bundled inside another spec (e.g., tiara-gitflow-spec), that parent spec's AGENTS.md and CONTRIBUTING.md will also reference these URLs and must be updated accordingly.

Release Process

Make changes to src/README.rst
Build: pipenv run make build/html dist/markdown
Review the output
Commit the source changes and the built dist/markdown/ output
Publish: pipenv run make publish

Rules

Do NOT modify this spec inside a consuming repository. Changes MUST be made upstream in this repository.
The dist/markdown/ directory is committed so that consuming repositories have access to the agent-consumable output without needing to build.

2.1 KiB Raw Blame History