diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css new file mode 100644 index 0000000..87deafc --- /dev/null +++ b/docs/stylesheets/extra.css @@ -0,0 +1,13 @@ +:root { + --md-primary-fg-color: #00758F; + --md-primary-fg-color--light: #0099b8; + --md-primary-fg-color--dark: #005f73; + --md-accent-fg-color: #00758F; +} + +[data-md-color-scheme="slate"] { + --md-primary-fg-color: #0099b8; + --md-primary-fg-color--light: #33b4cf; + --md-primary-fg-color--dark: #00758F; + --md-accent-fg-color: #0099b8; +} diff --git a/docs/superpowers/plans/2026-04-30-release-v0.4.6.md b/docs/superpowers/plans/2026-04-30-release-v0.4.6.md new file mode 100644 index 0000000..11dfbf9 --- /dev/null +++ b/docs/superpowers/plans/2026-04-30-release-v0.4.6.md @@ -0,0 +1,334 @@ +# Release v0.4.6 Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Ship v0.4.6 to PyPI including the mypy cleanup, pre-commit hook, CLAUDE.md improvements, and docs UI polish — once the ui-refactor work is located or created. + +**Architecture:** Standard release flow: UI branch merged first → version bump + changelog on a release branch → local build to verify artifacts → `gh release create` triggers the OIDC publish workflow automatically. + +**Tech Stack:** Python / setuptools, MkDocs Material, GitHub Actions OIDC publish, `gh` CLI + +--- + +## Files touched + +| File | Change | +|------|--------| +| `pyproject.toml` | Bump `version` to `0.4.6` | +| `CHANGELOG.md` | Add `[0.4.6]` entry | +| `mkdocs.yml` | UI polish (Task 1) | +| `docs/index.md` | UI polish if needed (Task 1) | + +--- + +## Task 1: Resolve the ui-refactor branch + +The `feat/ui-refactor` branch does not exist on the remote. Dark mode is already wired in `mkdocs.yml` (both `default` and `slate` schemes). Decide one of two paths: + +**Path A — branch exists locally somewhere:** push it, open a PR against `main`, merge, then continue to Task 2. + +**Path B — start fresh now:** create the branch, make the UI improvements below, merge, then continue. + +- [ ] **Check for a local branch** + + ```bash + git branch | grep -i refactor + ``` + + If found, push it: + ```bash + git push -u origin + gh pr create --title "docs(ui): ui-refactor" --body "UI polish for v0.4.6" + ``` + Merge it, pull main, then jump to Task 2. + +- [ ] **If not found — create the branch** + + ```bash + git checkout -b docs/ui-refactor + ``` + +- [ ] **Apply UI improvements to `mkdocs.yml`** + + Replace the current `palette` + `features` block with the version below. + Key changes: `primary` and `accent` moved from generic `blue` to the + OpenNMS brand teal (`#00758F`), dark scheme gets a matching override, + and three additional nav features are enabled. + + ```yaml + theme: + name: material + palette: + - scheme: default + primary: custom + accent: custom + toggle: + icon: material/brightness-7 + name: Switch to dark mode + - scheme: slate + primary: custom + accent: custom + toggle: + icon: material/brightness-4 + name: Switch to light mode + features: + - navigation.instant + - navigation.top + - navigation.tabs + - navigation.sections + - search.suggest + - search.highlight + - content.code.copy + - content.tooltips + + extra_css: + - stylesheets/extra.css + ``` + +- [ ] **Create `docs/stylesheets/extra.css`** + + ```css + :root { + --md-primary-fg-color: #00758F; + --md-primary-fg-color--light: #0099b8; + --md-primary-fg-color--dark: #005f73; + --md-accent-fg-color: #00758F; + } + + [data-md-color-scheme="slate"] { + --md-primary-fg-color: #0099b8; + --md-primary-fg-color--light: #33b4cf; + --md-primary-fg-color--dark: #00758F; + --md-accent-fg-color: #0099b8; + } + ``` + +- [ ] **Preview locally** + + ```bash + source .venv/bin/activate + mkdocs serve + ``` + + Open http://127.0.0.1:8000. Verify: + - Light mode loads with teal nav bar + - Dark mode toggle switches to slate scheme with teal accents + - API reference page renders correctly + +- [ ] **Commit and open PR** + + ```bash + git add mkdocs.yml docs/stylesheets/extra.css + git commit -m "docs(ui): brand teal theme + dark mode polish for v0.4.6" + git push -u origin docs/ui-refactor + gh pr create --title "docs(ui): brand teal theme + dark mode polish" \ + --body "Replaces generic blue with OpenNMS brand teal (#00758F), adds navigation.tabs/sections and content.tooltips, adds extra.css for scheme overrides. Preview: mkdocs serve." + ``` + +- [ ] **Wait for CI, merge** + + ```bash + gh pr checks --watch + gh pr merge --squash + git checkout main && git pull origin main + ``` + +--- + +## Task 2: Bump version and update CHANGELOG + +**Files:** `pyproject.toml`, `CHANGELOG.md` + +- [ ] **Create release branch** + + ```bash + git checkout -b chore/v0.4.6 + ``` + +- [ ] **Bump version in `pyproject.toml`** + + Change line 7: + ```toml + version = "0.4.6" + ``` + +- [ ] **Add CHANGELOG entry** + + Insert the following block immediately after the `# Changelog` header + and the format/semver note lines, before the existing `## [0.4.5]` entry: + + ```markdown + ## [0.4.6] - 2026-04-30 + + ### Added + + - **Pre-commit ruff hook** (`.pre-commit-config.yaml`): contributors now + get lint feedback before pushing. `CONTRIBUTING.md` updated with the + optional `pre-commit install` setup step. + - **`types-requests`** added to dev dependencies so `mypy` works on a fresh + `pip install -e ".[dev]"` without a separate manual install. + + ### Changed + + - **Docs UI**: OpenNMS brand teal (`#00758F`) replaces generic blue across + light and dark mode; `navigation.tabs`, `navigation.sections`, and + `content.tooltips` enabled. + - **`CLAUDE.md`** updated with required prefix, linting/type-check commands, + single-test example, `mkdocs serve`, exception hierarchy, and new-mixin + step-by-step instructions; redundant 42-line mixin file list removed. + + ### Fixed + + - **427 mypy errors** resolved across 51 files: + - All 49 mixin classes now inherit `_OpenNMSBase` so mypy resolves + `_get`/`_post`/`_put`/`_delete`/`_patch` through the MRO. + - `Optional[X]` annotations added wherever a typed parameter defaulted + to `None`. + - `dict[str, Any]` annotations added to mixed-type `params`/`data` dicts. + - `from __future__ import annotations` added to 8 files that use + `dict[str, Any]` subscript syntax, preserving Python 3.8 compatibility. + - `_OpenNMSBase` removed from `client.py`'s explicit base list (inherited + through mixins, eliminating the MRO conflict). + ``` + +- [ ] **Verify version appears correctly** + + ```bash + grep "^version" pyproject.toml + ``` + Expected: `version = "0.4.6"` + +- [ ] **Commit** + + ```bash + git add pyproject.toml CHANGELOG.md + git commit -m "chore: bump to v0.4.6" + ``` + +--- + +## Task 3: Build and verify the package locally + +**Files:** `dist/` (generated, gitignored) + +- [ ] **Build** + + ```bash + source .venv/bin/activate + pip install build -q + python -m build + ``` + + Expected output ends with: + ``` + Successfully built opennms_api_wrapper-0.4.6.tar.gz and opennms_api_wrapper-0.4.6-py3-none-any.whl + ``` + +- [ ] **Inspect the wheel contents** + + ```bash + python -m zipfile -l dist/opennms_api_wrapper-0.4.6-py3-none-any.whl | head -30 + ``` + + Verify `opennms_api_wrapper/` files are present and no unwanted files + (`.env`, `__pycache__`, `dist/`, `docs/`) are included. + +- [ ] **Smoke-test the wheel in a clean env** + + ```bash + python3 -m venv /tmp/test-046 + /tmp/test-046/bin/pip install dist/opennms_api_wrapper-0.4.6-py3-none-any.whl -q + /tmp/test-046/bin/python -c " + import opennms_api_wrapper as opennms + print(opennms.__version__) + c = opennms.OpenNMS('http://localhost:8980', 'admin', 'admin') + print(type(c)) + " + ``` + + Expected: + ``` + 0.4.6 + + ``` + +- [ ] **Run full test suite one last time** + + ```bash + source .venv/bin/activate + pytest tests/ -v + ``` + Expected: `490 passed` + +--- + +## Task 4: Open PR, merge, and cut the release + +- [ ] **Push and open PR** + + ```bash + git push -u origin chore/v0.4.6 + gh pr create --title "chore: bump to v0.4.6" \ + --body "$(cat <<'EOF' + Release v0.4.6. See CHANGELOG.md for full details. + + ## Included since v0.4.5 + - Pre-commit ruff hook + - 427 mypy errors fixed (51 files) + - CLAUDE.md improvements + - types-requests in dev deps + - Docs UI: brand teal theme + dark mode polish + EOF + )" + ``` + +- [ ] **Wait for CI to go green** + + ```bash + gh pr checks --watch + ``` + All jobs must pass before merging. + +- [ ] **Merge** + + ```bash + gh pr merge --squash + git checkout main && git pull origin main + ``` + +- [ ] **Cut the release (triggers PyPI publish)** + + ```bash + gh release create v0.4.6 \ + --title "v0.4.6" \ + --notes "$(cat <<'EOF' + ## What's new + + ### Added + - Pre-commit ruff hook for contributors + - `types-requests` in dev dependencies + + ### Changed + - Docs: OpenNMS brand teal theme + dark mode polish + - Improved `CLAUDE.md` (commands, exception tree, new-mixin guide) + + ### Fixed + - 427 mypy errors resolved across 51 files (mixin inheritance, Optional annotations, Python 3.8 compat) + + **Full changelog:** https://github.com/cnewkirk/opennms-api-wrapper/blob/main/CHANGELOG.md + EOF + )" + ``` + +- [ ] **Confirm PyPI publish succeeded** + + ```bash + gh run list --workflow publish.yml --limit 3 + ``` + Wait for the run triggered by the release to show `completed / success`. + + Then verify: + ```bash + pip index versions opennms-api-wrapper 2>/dev/null | head -3 + ``` + Expected: `0.4.6` listed as the latest version. diff --git a/mkdocs.yml b/mkdocs.yml index b40e51a..57db338 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -8,23 +8,29 @@ theme: name: material palette: - scheme: default - primary: blue - accent: blue + primary: custom + accent: custom toggle: icon: material/brightness-7 name: Switch to dark mode - scheme: slate - primary: blue - accent: blue + primary: custom + accent: custom toggle: icon: material/brightness-4 name: Switch to light mode features: - navigation.instant - navigation.top + - navigation.tabs + - navigation.sections - search.suggest - search.highlight - content.code.copy + - content.tooltips + +extra_css: + - stylesheets/extra.css plugins: - search