Add RELEASING.md

[folathecoder]

Document the release process: green-gate preflight, TestPyPI dry run,
secure token handling (read -rs into UV_PUBLISH_TOKEN), --extra-index-url for
dependencies, publish to PyPI, and an annotated tag + GitHub release from the
CHANGELOG section.

[qodo-code-review]

PR Summary by Qodo

Add RELEASING.md with secure, repeatable release checklist

📝 Documentation 🕐 Less than 5 minutes

AI Description

• Document the end-to-end release workflow from version bump through GitHub release.
• Add a TestPyPI dry-run path and clean-environment install verification.
• Specify secure token handling via UV_PUBLISH_TOKEN and annotated tagging steps.

Diagram

graph TD
  A["Maintainer"] --> B["RELEASING.md"] --> C["Preflight gate"] --> D["Build + twine check"] --> E["TestPyPI publish"] --> F["Test install (extra index)"] --> G["PyPI publish"] --> H["Annotated tag + GitHub release"]

  subgraph Legend
    direction LR
    _doc["Doc"] ~~~ _step["Step"]
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Automate releases via GitHub Actions (trusted publishing)

• ➕ Reduces manual steps and token-handling risk
• ➕ Creates repeatable, audited release workflow
• ➕ Can enforce gates (tests/lint/build) before publishing
• ➖ Requires CI/CD setup and PyPI trusted publisher configuration
• ➖ More upfront work than documentation-only change

2. Use a dedicated release tool (e.g., hatch/poetry/towncrier)

• ➕ Standardizes versioning/changelog/tagging
• ➕ Often supports one-command build+publish flows
• ➖ Adds/changes tooling and contributor workflow
• ➖ May conflict with current uv-based approach

Recommendation: For now, the documented manual checklist is appropriate and low-risk, especially with the emphasis on TestPyPI and secure token input. If releases become frequent or multi-maintainer, consider following up with GitHub Actions trusted publishing to remove manual token handling and enforce the preflight gate automatically.

Files changed (1) +115 / -0

Documentation (1) +115 / -0

RELEASING.mdAdd secure, step-by-step release process guide +115/-0

Add secure, step-by-step release process guide

• Introduces a comprehensive release checklist covering preflight validation, build verification, TestPyPI dry-run publishing, and final PyPI publishing. Documents secure token handling via 'read -rs' into 'UV_PUBLISH_TOKEN', clean-environment install verification, and creating an annotated tag plus GitHub release from changelog-aligned notes.

RELEASING.md

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0) 📜 Skill insights (0)

1. Fixed /tmp venv paths 🐞 Bug ☼ Reliability

Description

RELEASING.md hard-codes venv locations under /tmp (e.g. /tmp/testpypi, /tmp/pypi) and deletes
them with rm -rf, which can fail or collide if a previous run left the directory behind or two
releases are attempted concurrently. This makes the documented release workflow unnecessarily
fragile.

Code

RELEASING.md[R70-94]

+uv venv /tmp/testpypi
+uv pip install --python /tmp/testpypi \
+  --index-url https://test.pypi.org/simple/ \
+  --extra-index-url https://pypi.org/simple/ \
+  agentling
+/tmp/testpypi/bin/python -c "import agentling; print(agentling.__version__)"
+unset UV_PUBLISH_TOKEN && rm -rf /tmp/testpypi
+```
+
+## 5. Publish to PyPI
+
+```bash
+read -rs UV_PUBLISH_TOKEN && export UV_PUBLISH_TOKEN   # PyPI token this time
+uv publish                                             # default target is real PyPI
+unset UV_PUBLISH_TOKEN
+```
+
+Confirm a clean-environment install:
+
+```bash
+uv venv /tmp/pypi
+uv pip install --python /tmp/pypi agentling
+/tmp/pypi/bin/python -c "import agentling; print(agentling.__version__)"
+rm -rf /tmp/pypi
+```

Evidence

The guide creates and removes virtual environments at fixed /tmp paths for both TestPyPI and PyPI
verification, which is inherently prone to collisions and leftover-directory failures.

RELEASING.md[69-77]
RELEASING.md[89-94]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The release guide creates virtualenvs in fixed locations under `/tmp` and then cleans them with `rm -rf`. If those paths already exist (e.g. an interrupted prior run) or are used by another process, the documented steps may fail or behave unexpectedly.

### Issue Context
This is documentation, but it describes commands users will copy/paste during a release. Using unique temp directories and a `trap` makes the process more robust and ensures cleanup even if a command fails.

### Fix Focus Areas
- RELEASING.md[69-77]
- RELEASING.md[89-94]

### Suggested change (example)
Replace fixed `/tmp/...` dirs with a unique temp dir and ensure cleanup:

```bash
TMP_VENV=$(mktemp -d /tmp/agentling-testpypi.XXXXXX)
trap 'rm -rf "$TMP_VENV"; unset UV_PUBLISH_TOKEN' EXIT

uv venv "$TMP_VENV"
uv pip install --python "$TMP_VENV" \
 --index-url https://test.pypi.org/simple/ \
 --extra-index-url https://pypi.org/simple/ \
 agentling
"$TMP_VENV"/bin/python -c "import agentling; print(agentling.__version__)"
```

Do the same for the PyPI verification venv section.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[qodo-code-review]

1. Fixed /tmp venv paths 🐞 Bug ☼ Reliability

RELEASING.md hard-codes venv locations under /tmp (e.g. /tmp/testpypi, /tmp/pypi) and deletes
them with rm -rf, which can fail or collide if a previous run left the directory behind or two
releases are attempted concurrently. This makes the documented release workflow unnecessarily
fragile.

Agent Prompt

### Issue description
The release guide creates virtualenvs in fixed locations under `/tmp` and then cleans them with `rm -rf`. If those paths already exist (e.g. an interrupted prior run) or are used by another process, the documented steps may fail or behave unexpectedly.

### Issue Context
This is documentation, but it describes commands users will copy/paste during a release. Using unique temp directories and a `trap` makes the process more robust and ensures cleanup even if a command fails.

### Fix Focus Areas
- RELEASING.md[69-77]
- RELEASING.md[89-94]

### Suggested change (example)
Replace fixed `/tmp/...` dirs with a unique temp dir and ensure cleanup:

```bash
TMP_VENV=$(mktemp -d /tmp/agentling-testpypi.XXXXXX)
trap 'rm -rf "$TMP_VENV"; unset UV_PUBLISH_TOKEN' EXIT

uv venv "$TMP_VENV"
uv pip install --python "$TMP_VENV" \
  --index-url https://test.pypi.org/simple/ \
  --extra-index-url https://pypi.org/simple/ \
  agentling
"$TMP_VENV"/bin/python -c "import agentling; print(agentling.__version__)"
```

Do the same for the PyPI verification venv section.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools