docs: add README, changelog and release procedurev0.1.0

README covers what the project deliberately does not do (no POP, IMAP or
SMTP, no send in v1, no confirmation dialogs), the verified dependency
versions, build and test commands, the full config format with the reasons
behind its two surprises, the keybinding table, and the security posture of
the message view.

Two facts in it were checked rather than assumed: the `spam` and
`load_remote` actions are registered but have no default binding, so they
are documented as unreachable until bound; and the attachment path guard
does exist as described. The Release build was also verified to pass all 11
test binaries, which matters because Q_ASSERT compiles out there and one of
the cid: invariants leans on an assertion in debug.

CHANGELOG.md follows Keep a Changelog and records 0.1.0 along with the
current known limitations. docs/RELEASING.md records what semver means for
a mail client (the config format and action names are the public interface)
and the steps, including that the version is bumped in exactly one place.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

1 files changed, 83 insertions, 0 deletions

diff --git a/docs/RELEASING.md b/docs/RELEASING.md
new file mode 100644
index 0000000..ca1c6d2
--- /dev/null
+++ b/docs/RELEASING.md
@@ -0,0 +1,83 @@
+# Releasing
+
+Short enough to follow without thinking, which is the point: releases here
+are infrequent enough to forget the order.
+
+## Versioning
+
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html). The public
+interface of a desktop mail client is not an API; for this project it means:
+
+- the configuration file format (section names, key names, their meaning)
+- the keybinding action names bindable from `[keys]`
+- the command-line interface
+- where configuration is read from
+
+Below 1.0.0 those may change in a minor release. 1.0.0 is the point at which
+they stop changing under users, which is a decision to make deliberately
+rather than a milestone that arrives on its own.
+
+- **MAJOR**: a config file that worked before now does not, or an action
+  name is removed or changes meaning.
+- **MINOR**: a feature, a new action name, a new config key that older
+  configs simply do not set.
+- **PATCH**: a fix that leaves all of the above alone.
+
+## Steps
+
+1. **Confirm the tree is clean and the tests pass.**
+
+   ```bash
+   git status --short
+   cmake --build build && ctest --test-dir build --output-on-failure
+   ```
+
+2. **Bump the version.** It is declared in exactly one place, the
+   `project()` call in the top-level `CMakeLists.txt`; `src/version.h.in`
+   generates `version.h` from it. Do not write the number anywhere else.
+
+   ```cmake
+   project(qtmaildir VERSION 0.2.0 LANGUAGES CXX)
+   ```
+
+3. **Move `Unreleased` in `CHANGELOG.md`** to a new dated section, and open
+   an empty `Unreleased` above it.
+
+   ```markdown
+   ## [Unreleased]
+
+   Nothing yet.
+
+   ## [0.2.0] - 2026-09-01
+   ```
+
+4. **Rebuild and check the version actually changed.** The generated header
+   is a build artifact, so a stale build directory will happily report the
+   old number.
+
+   ```bash
+   cmake -S . -B build && cmake --build build
+   ./build/src/qtmaildir --version
+   ```
+
+5. **Commit and tag.** Tags are annotated and signed, like every commit in
+   this repository.
+
+   ```bash
+   git add CMakeLists.txt CHANGELOG.md
+   git commit -S -m "release: 0.2.0"
+   git tag -s v0.2.0 -m "qtmaildir 0.2.0"
+   ```
+
+6. **Verify the tag is signed**, then push if there is a remote.
+
+   ```bash
+   git tag -v v0.2.0
+   git push && git push --tags
+   ```
+
+## After a release that changes the config format
+
+Note it in the changelog under `Changed` with the old and new spelling side
+by side. A user whose config silently stops working will not go looking for
+a version number to blame.