100 lines
2.1 KiB
Markdown
100 lines
2.1 KiB
Markdown
# 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.
|