Skip to content

Phase 5: README, CI workflows, and changelog#8

Merged
amcheste merged 1 commit into
developfrom
feat/phase-5-docs-ci
Apr 25, 2026
Merged

Phase 5: README, CI workflows, and changelog#8
amcheste merged 1 commit into
developfrom
feat/phase-5-docs-ci

Conversation

@amcheste-ai-agent
Copy link
Copy Markdown
Contributor

@amcheste-ai-agent amcheste-ai-agent Bot commented Apr 25, 2026

Summary

The publishing-prep phase: everything needed to ship v0.1.0 to PyPI from a tag push.

File What
.github/workflows/tests.yml ruff + pytest + coverage on push/PR to develop and main, matrixed on Python 3.11, 3.12, 3.13
.github/workflows/release.yml Triggers on v*.*.* tag push: uv build → PyPI publish via OIDC trusted publishing (no stored token)
README.md Replaces the Phase 0 stub. User-facing: install, quickstart through doctor, Claude Desktop config snippet, tool list, GitHub mirror pattern, security, limitations
CHANGELOG.md Keep a Changelog format. Seeded with the v0.1.0 entry; v0.2 plans live under [Unreleased] so the trajectory is visible

Pre-merge prerequisite for the release workflow

Before the first v*.*.* tag push will actually publish to PyPI, register the package as a pending trusted publisher on PyPI:

  1. https://pypi.org/manage/account/publishing/ → Add a new pending publisher
  2. Fill in:
    • Project name: overleaf-mcp-server
    • Owner: amcheste
    • Repository name: overleaf-mcp
    • Workflow filename: release.yml
    • Environment name: pypi (matches the environment.name field in release.yml)

This doesn't block merging this PR — only blocks the actual tag-push publish. We can land Phase 5 first and do the PyPI form whenever you're ready to tag.

After this merges

Suggest re-running /setup-repo (or one gh api call) to require the Tests job as a status check on develop and main. The check name will be Test (Python 3.11) / Test (Python 3.12) / Test (Python 3.13) — pick whichever set you want gating merges. I'd recommend requiring all three.

Test results

  • 119 tests pass, 100% coverage on measured modules (threshold 80%)
  • Ruff clean
  • Workflows lint cleanly (validated by GitHub Actions schema, no act run needed before merge)

Commits

  • docs: README, CI workflows, and changelog

Test plan

  • CI runs green on this PR (the tests.yml workflow's first run validates itself)
  • Reviewer skims README for tone / accuracy
  • Reviewer registers the PyPI pending publisher when ready

🤖 Generated with Claude Code

@amcheste-ai-agent @claude @amcheste
docs: README, CI workflows, and changelog
97241b5 
Phase 5 ships the artifacts needed to publish v0.1.0:

- .github/workflows/tests.yml — runs ruff + pytest with coverage on
  every push and PR to develop/main. Matrix on Python 3.11, 3.12, 3.13.
  Configures git identity inside the runner so git_client tests can
  exercise real git against local bare repos.

- .github/workflows/release.yml — triggers on v*.*.* tag pushes.
  Builds sdist + wheel via 'uv build', then publishes to PyPI using
  trusted publishing (OIDC). No stored API token. The publish job
  uses the 'pypi' GitHub Environment so PyPI's pending-publisher
  config can pin the trust to this exact workflow path.

- README.md — replaces the Phase 0 stub. Sections: what it is / is
  not, requirements, install, quick start through 'doctor', the
  Claude Desktop config snippet, tool list, GitHub mirror pattern,
  security notes, known limitations, contributing, license.

- CHANGELOG.md — Keep a Changelog format with the v0.1.0 entry
  enumerating the five tools, transport entry points, CLI surface,
  credential handling, and config/cache locations. v0.2 plans live
  under [Unreleased] so the trajectory is visible without committing
  the API.

Pre-merge prerequisite for the release workflow to succeed on its
first tag push: register 'overleaf-mcp-server' on PyPI as a pending
trusted publisher pointing at amcheste/overleaf-mcp + release.yml +
the 'pypi' environment.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@amcheste-ai-agent amcheste-ai-agent Bot requested a review from amcheste April 25, 2026 19:14
@amcheste-ai-agent amcheste-ai-agent Bot mentioned this pull request Apr 25, 2026
Merged
2 tasks
@amcheste Graphite App
Copy link
Copy Markdown
Owner

amcheste commented Apr 25, 2026 •
edited
Loading

Merge activity

  • Apr 25, 7:22 PM UTC: A user started a stack merge that includes this pull request via Graphite.
  • Apr 25, 7:22 PM UTC: @amcheste merged this pull request with Graphite.

@amcheste amcheste merged commit 15e3d0c into develop Apr 25, 2026
4 checks passed
@amcheste-ai-agent amcheste-ai-agent Bot mentioned this pull request Apr 25, 2026
Merged
3 tasks
@amcheste-ai-agent amcheste-ai-agent Bot deleted the feat/phase-5-docs-ci branch April 25, 2026 19:24
amcheste added a commit to amcheste/mac-dev-setup that referenced this pull request Apr 26, 2026
@amcheste @claude
chore(skills): sync setup-repo and publish-release with handbook v0.1…
f34627b 
….0 (#75)

## Summary
Two related corrections to the canonical Claude Code skills in this repo, bringing them in line with the conventions documented in [amcheste/engineering-handbook v0.1.0](https://github.com/amcheste/engineering-handbook/releases/tag/v0.1.0).

### \`claude-skills/setup-repo/SKILL.md\`
Adds **Step 6: verify CODEOWNERS routing**. Without \`.github/CODEOWNERS\`, bot-authored PRs (via the \`amcheste-ai-agent\` GitHub App) don't auto-route to a human reviewer and disappear from review queues like Graphite.

The new step checks for the file and surfaces the gap in the summary; \`setup-repo\` still doesn't write to the repo itself, so the remediation is a follow-up PR adding the file.

**How this was found:** [overleaf-mcp#8](amcheste/overleaf-mcp#8) didn't show up in @amcheste's review queue. The repo had been through \`/setup-repo\` but never had \`CODEOWNERS\` added. [overleaf-mcp#9](amcheste/overleaf-mcp#9) is the follow-up PR adding the file.

### \`claude-skills/publish-release/SKILL.md\`
Step 2 was opening a \`develop → main\` **GitHub PR** for the release promotion. That contradicts the rule documented in the [Branching Strategy philosophy §5](https://github.com/amcheste/engineering-handbook/blob/main/docs/philosophies/branching-strategy.md#5-releases-preserve-commit-ancestry--cli-merge-not-ui-merge) and in \`~/.claude/CLAUDE.md\`: GitHub's merge button squash-merges by default, which collapses commit ancestry and causes merge conflicts on every subsequent release.

The fix is a CLI \`--no-ff\` merge. Step 2 now documents:

\`\`\`bash
git fetch origin
git checkout main && git pull
git merge --no-ff origin/develop -m "chore: release v<version>"
git push origin main
\`\`\`

Also adds a **branch-protection note**: with \`enforce_admins: true\` + required-PR review (the standard \`setup-repo\` config), the CLI push to \`main\` is rejected. The skill now documents the toggle dance (disable, push, re-enable) and notes the App needs \`Administration: Read & Write\` to perform it. Same dance applies to the \`v*\` tag ruleset for Step 3.

**Minor cleanup:** hardcoded \`mac-dev-setup\` URL in the Summary section becomes a \`<repo>\` placeholder.

## Test plan
- [ ] CI (\`Lint\`, \`Commit Lint\`) passes.
- [ ] Skills render cleanly when read by Claude Code.
- [ ] After merge: re-sync local \`~/.claude/skills/\` from this repo (via your usual setup script) and run \`/setup-repo amcheste/<some-repo>\` to confirm Step 6 fires.

## Related
- engineering-handbook v0.1.0 — release that codified these conventions.
- overleaf-mcp#9 — concrete PR adding CODEOWNERS to a repo that was missing it.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: amcheste <13696614+amcheste@users.noreply.github.com>
amcheste-ai-agent Bot pushed a commit that referenced this pull request Apr 26, 2026
@amcheste-ai-agent @claude @amcheste
chore: add .github/CODEOWNERS routing all PRs to @amcheste
b314648 
Without this file, App-authored PRs in this repo had no auto-routing
to a human reviewer — they simply didn't appear in @amcheste's review
queue (e.g. Graphite, GitHub's own review filter). This was visible
on PR #8, which had no assignee, no reviewer, and no codeowner so it
was effectively invisible.

CODEOWNERS pattern matches every other repo in @amcheste's account
and is the canonical wiring point referenced in the engineering
handbook's Claude Bot Account design note.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: amcheste <13696614+amcheste@users.noreply.github.com>
amcheste added a commit that referenced this pull request Apr 29, 2026
@amcheste @claude
chore: add .github/CODEOWNERS routing all PRs to @amcheste (#9)
bf042e6 
## Summary
This repo had no \`CODEOWNERS\` file, which meant App-authored PRs (like #8) didn't auto-route to @amcheste for review. They simply weren't visible in his review queue (Graphite, GitHub's review-requested filter, etc.) until someone manually added a reviewer.

This PR fixes the gap.

\`* @amcheste\` matches the canonical wiring used in every other repo in this account, and pairs with the bot-account pattern described in the [Claude Bot Account design note](https://github.com/amcheste/engineering-handbook/blob/main/docs/design/claude-bot-account.md).

## Effect after merge
- Every new PR opened on this repo (regardless of author — human, bot, or App) auto-requests review from @amcheste.
- Existing PR #8 already had a reviewer added manually; future ones won't need that.

## Test plan
- [ ] Open a tiny test PR after merge and confirm @amcheste is auto-requested as reviewer.
- [ ] PR appears in @amcheste's Graphite / GitHub review queue without manual intervention.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: amcheste <13696614+amcheste@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@amcheste amcheste amcheste approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@amcheste @amcheste-ai-agent