# 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:

```sh
pipenv install
```

---

## Building

### HTML

```sh
pipenv run make build/html
```

Output: `build/html/`

### Markdown (agent-consumable)

```sh
pipenv run make dist/markdown
```

Output: `dist/markdown/`

### Both + publish

```sh
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:

```sh
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

1. Make changes to `src/README.rst`
2. Build: `pipenv run make build/html dist/markdown`
3. Review the output
4. Commit the source changes and the built `dist/markdown/` output
5. 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.