conventional-release 0.1.0__tar.gz

conventional_release-0.1.0/.github/dependabot.yml

@@ -0,0 +1,14 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly
+    commit-message:
+      prefix: ci
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: monthly
+    commit-message:
+      prefix: build

conventional_release-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,8 @@
+<!-- Title: a conventional commit, e.g. "feat(cli): add --json". It becomes the changelog line. -->
+
+## What and why
+
+## How it was tested
+
+<!-- For a breaking change, add a footer:
+BREAKING CHANGE: what users must do differently -->

conventional_release-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+      - run: make lint typecheck
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+        with:
+          python-version: ${{ matrix.python }}
+      - run: make tests
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+      - run: uv build
+      - run: uvx twine check --strict dist/*

conventional_release-0.1.0/.github/workflows/claude-review.yml

@@ -0,0 +1,174 @@
+name: claude-review
+
+# Two jobs, one action:
+#   review  — every non-draft PR gets an automatic review, posted as inline comments plus one
+#             sticky summary.
+#   mention — "@claude <question>" (or "@claude review" after a fix push) in a PR/issue comment
+#             gets an answer. Maintainers only: see the `if` on that job.
+#
+# Authenticated with a Claude subscription OAuth token (CLAUDE_CODE_OAUTH_TOKEN, from
+# `claude setup-token`). Until that secret exists the jobs skip with a notice instead of failing:
+# a missing reviewer must not turn a PR red.
+#
+# Public-repo safety:
+# - PRs from forks get no secrets on `pull_request`, so they are skipped with the same notice.
+#   Never switch this to `pull_request_target`: that hands the token to code from a stranger's fork.
+# - `issue_comment` runs WITH secrets on any PR, forks included, so the mention job only answers
+#   comments from the repo owner, members and collaborators.
+# - The reviewer is read-only on the repo (contents: read). It can comment; it can never push.
+#
+# The action refuses to run a workflow file that differs from the copy on the default branch
+# (anti-tamper), so a change to THIS file must be merged on its own before a PR carrying the
+# same change can be reviewed.
+
+on:
+  pull_request:
+    # Not on every push, because each round uses the plan's quota. After fixes, ask again with
+    # "@claude review".
+    types: [opened, reopened, ready_for_review]
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+
+permissions:
+  contents: read
+  pull-requests: write
+  issues: write
+  id-token: write
+  actions: read
+
+# Keyed on event, number and actor. Without the event, the reviewer's own first inline comment
+# (a pull_request_review_comment) cancels the review that is still running. Without the actor,
+# the mention job's progress comment cancels the run that posted it.
+concurrency:
+  group: claude-${{ github.event_name }}-${{ github.event.pull_request.number || github.event.issue.number }}-${{ github.actor }}
+  cancel-in-progress: true
+
+jobs:
+  review:
+    name: claude-review
+    if: >
+      github.event_name == 'pull_request' &&
+      github.event.pull_request.draft == false &&
+      !startsWith(github.event.pull_request.title, 'chore(release):') &&
+      github.actor != 'dependabot[bot]'
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - id: token
+        name: Is the reviewer configured?
+        env:
+          TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+        run: |
+          if [ -n "$TOKEN" ]; then
+            echo "enabled=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "enabled=false" >> "$GITHUB_OUTPUT"
+            echo "::notice title=claude-review skipped::CLAUDE_CODE_OAUTH_TOKEN is not available (not set, or a PR from a fork)."
+          fi
+
+      - if: steps.token.outputs.enabled == 'true'
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0  # the review needs the base branch to diff against
+
+      - if: steps.token.outputs.enabled == 'true'
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          use_sticky_comment: true
+          prompt: |
+            REPO: ${{ github.repository }}
+            PR NUMBER: ${{ github.event.pull_request.number }}
+
+            You are reviewing a pull request for conventional-release, a Python CLI and a set of
+            reusable GitHub workflows that other projects call to write their CHANGELOG, bump
+            versions, tag releases and publish them. Other repositories run this code in their
+            release pipelines, so a regression breaks releases we cannot see.
+
+            Read CONTRIBUTING.md and the README first. They define the contract:
+            - The CHANGELOG output is byte-compatible with standard-version: `## X.Y.Z (date)`, two
+              blank lines, `### Section`, `* **scope:** subject ([#N](…/issues/N)) ([sha](…))`.
+              Any change to the rendered shape (cliff.py templates, section order, link format) is
+              a breaking change for users, even if the tests were updated to match.
+            - The reusable workflows (.github/workflows/tag.yml, pr-title.yml) are a public API
+              called as `@v0`: their inputs, outputs (released, version, tag) and default
+              tool-spec must not change incompatibly in a minor release.
+            - The CLI's commands, flags, exit codes and config keys (.conventional-release.toml
+              and [tool.conventional-release]) are public API too.
+            - Version files are edited textually, one line only. Comments and formatting elsewhere
+              in the file must survive.
+            - PR titles follow Conventional Commits. The title becomes the changelog line.
+
+            Look for, in this order:
+            1. Correctness bugs: version bump rules (breaking → major, feat → minor, fix → patch;
+               the first release keeps the version in the file), tag detection after a squash
+               merge, git edge cases (no tags, no remote, dirty tree, existing tag or branch).
+            2. Breaking changes to the public API above that the title does not mark with `!` and a
+               BREAKING CHANGE footer.
+            3. Workflow security: secrets reaching fork PRs, `pull_request_target`, untrusted
+               GitHub expressions (PR titles, comment bodies) interpolated straight into `run:`
+               instead of passed through `env:`, permissions wider than the job needs, or
+               publishing without trusted publishing.
+            4. New behaviour without a test. Tests build throwaway git repos in tmp_path, see
+               tests/conftest.py.
+            5. README drift: a changed command, flag, config key or workflow input that the
+               README still documents the old way.
+
+            Do NOT comment on formatting, import order or line length. ruff, mypy --strict and
+            actionlint already gate those in CI. Do not restate the PR description back.
+
+            Use `gh pr diff` and `gh pr view` to see the change. Post specific findings as inline
+            comments on the exact lines (mcp__github_inline_comment__create_inline_comment).
+            Then post ONE summary comment via `gh pr comment`: a short verdict, the findings
+            ranked by severity, and anything you could not verify. If there is nothing
+            significant, say so in two sentences. A short honest review beats a long padded one.
+
+            Budget: you have a hard cap of 60 tool calls, and the run fails if you exceed it. Start
+            from `gh pr diff --name-only` and `gh pr diff`. Read a file in full only when the diff
+            alone cannot answer the question. Post the summary comment no later than your 45th
+            call, and say what you did not get to. An unposted review is worth nothing.
+          claude_args: |
+            --max-turns 60
+            --allowed-tools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Read,Grep,Glob"
+
+  mention:
+    name: claude-mention
+    # Maintainers only: issue_comment runs with secrets even on fork PRs, so anyone else could
+    # spend the plan's quota. Never react to the bot's own comments, or it talks to itself forever.
+    if: >
+      (github.event_name == 'issue_comment' || github.event_name == 'pull_request_review_comment') &&
+      contains(github.event.comment.body, '@claude') &&
+      contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association) &&
+      github.actor != 'claude[bot]'
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - id: token
+        name: Is the reviewer configured?
+        env:
+          TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+        run: |
+          if [ -n "$TOKEN" ]; then
+            echo "enabled=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "enabled=false" >> "$GITHUB_OUTPUT"
+            echo "::notice title=claude-mention skipped::CLAUDE_CODE_OAUTH_TOKEN is not set."
+          fi
+
+      - if: steps.token.outputs.enabled == 'true'
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - if: steps.token.outputs.enabled == 'true'
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          # No prompt means tag mode: it answers the @claude comment in context. "@claude review"
+          # is a full review of the head, so it gets the review job's budget. A question gets 20.
+          claude_args: |
+            --max-turns ${{ contains(github.event.comment.body, '@claude review') && '60' || '20' }}
+            --append-system-prompt "You have a hard cap on tool calls (--max-turns) and the run FAILS the moment you exceed it. Work from `gh pr diff --name-only` and `gh pr diff`; read a file in full only when the diff cannot answer the question. Post your answer (for a review request, one summary comment via `gh pr comment`) by three quarters of that budget at the latest, saying plainly what you did not get to."
+            --allowed-tools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh issue view:*),Read,Grep,Glob"

conventional_release-0.1.0/.github/workflows/pr-title.yml

@@ -0,0 +1,36 @@
+name: pr-title
+
+# Reusable: the PR title becomes the squash commit subject, and that subject becomes the
+# changelog line — so the title must be a conventional commit. Make this check required.
+
+on:
+  workflow_call:
+    inputs:
+      tool-spec:
+        description: "What `uvx --from` installs, e.g. `conventional-release==0.1.0`"
+        type: string
+        default: "conventional-release>=0.1,<0.2"
+      working-directory:
+        description: Directory holding the project's conventional-release config
+        type: string
+        default: "."
+
+jobs:
+  pr-title:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      # For the project's configured types; nothing from the PR is executed.
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@v10.2.0
+
+      - name: Title is a conventional commit
+        working-directory: ${{ inputs.working-directory }}
+        env:
+          TOOL: ${{ inputs.tool-spec }}
+          TITLE: ${{ github.event.pull_request.title }}
+        run: uvx --from "$TOOL" conventional-release check-title "$TITLE"

conventional_release-0.1.0/.github/workflows/pr.yml

@@ -0,0 +1,16 @@
+name: pr
+
+# This repo checks its own PR titles with its own checkout of the tool.
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize, reopened]
+
+permissions:
+  contents: read
+
+jobs:
+  pr-title:
+    uses: ./.github/workflows/pr-title.yml
+    with:
+      tool-spec: "."

conventional_release-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,78 @@
+name: release
+
+# The project releases itself: `make release` opens the release PR; merging it lands here.
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  tag:
+    uses: ./.github/workflows/tag.yml
+    permissions:
+      contents: write
+    with:
+      tool-spec: "."
+
+  build:
+    needs: tag
+    if: needs.tag.outputs.released == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ needs.tag.outputs.tag }}
+      - uses: astral-sh/setup-uv@v10.2.0
+      - run: uv build
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  testpypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write  # trusted publishing, no token stored anywhere
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  pypi:
+    needs: [tag, testpypi]
+    runs-on: ubuntu-latest
+    environment: pypi  # required reviewer: the maintainer
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  # `uses: MdaaaaO/conventional-release/.github/workflows/tag.yml@v0` follows the latest 0.x.
+  major-tag:
+    needs: [tag, pypi]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ needs.tag.outputs.tag }}
+      - env:
+          TAG: ${{ needs.tag.outputs.tag }}
+        run: |
+          major="${TAG%%.*}"
+          git tag -f "$major" "$TAG^{commit}"
+          git push -f origin "refs/tags/$major"

conventional_release-0.1.0/.github/workflows/tag.yml

@@ -0,0 +1,79 @@
+name: tag
+
+# Reusable: the CI half of a release. Call it on every push to the default branch. When the
+# pushed commit is a squash-merged `chore(release): X.Y.Z`, it tags that commit vX.Y.Z and
+# publishes a GitHub Release with the version's CHANGELOG section; otherwise it does nothing.
+#
+# Run your publish jobs *after* it in the same workflow (`needs: tag`, `if: released`): a tag
+# pushed with GITHUB_TOKEN starts no other workflow, so `on: push: tags` would never fire.
+# The caller grants `contents: write`.
+
+on:
+  workflow_call:
+    inputs:
+      tool-spec:
+        description: "What `uvx --from` installs, e.g. `conventional-release==0.1.0`"
+        type: string
+        default: "conventional-release>=0.1,<0.2"
+      working-directory:
+        description: Directory of the project inside the repository
+        type: string
+        default: "."
+      github-release:
+        description: Publish a GitHub Release with the changelog section
+        type: boolean
+        default: true
+    outputs:
+      released:
+        description: "'true' when this run created the tag"
+        value: ${{ jobs.tag.outputs.released }}
+      version:
+        description: The released version, e.g. 1.4.0
+        value: ${{ jobs.tag.outputs.version }}
+      tag:
+        description: The tag, e.g. v1.4.0
+        value: ${{ jobs.tag.outputs.tag }}
+
+jobs:
+  tag:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    outputs:
+      released: ${{ steps.detect.outputs.released }}
+      version: ${{ steps.detect.outputs.version }}
+      tag: ${{ steps.detect.outputs.tag }}
+    defaults:
+      run:
+        working-directory: ${{ inputs.working-directory }}
+    env:
+      TOOL: ${{ inputs.tool-spec }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v10.2.0
+
+      - id: detect
+        name: Is this a release commit?
+        run: uvx --from "$TOOL" conventional-release detect --github-output
+
+      - name: Tag the release commit
+        if: steps.detect.outputs.released == 'true'
+        env:
+          VERSION: ${{ steps.detect.outputs.version }}
+        run: |
+          git config user.name  "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          uvx --from "$TOOL" conventional-release tag "$VERSION" --push
+
+      - name: GitHub Release
+        if: steps.detect.outputs.released == 'true' && inputs.github-release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          VERSION: ${{ steps.detect.outputs.version }}
+          TAG: ${{ steps.detect.outputs.tag }}
+        run: |
+          uvx --from "$TOOL" conventional-release notes "$VERSION" > "$RUNNER_TEMP/notes.md"
+          gh release create "$TAG" --title "$TAG" --notes-file "$RUNNER_TEMP/notes.md" --verify-tag

conventional_release-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+build/
+.coverage
+coverage.xml
+htmlcov/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/

conventional_release-0.1.0/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this project will be documented in this file. Generated by
+[conventional-release](https://github.com/MdaaaaO/conventional-release) from
+[Conventional Commits](https://www.conventionalcommits.org).
+
+## 0.1.0 (2026-09-25)
+
+
+### Features
+
+* standard-version-style changelog and release PRs from conventional commits ([12737d1](https://github.com/MdaaaaO/conventional-release/commit/12737d1e37eda9b5dc2dcd1e090d178a2af90a64))
+
+
+### Documentation
+
+* readme, contributing guide and security policy ([3ff7da2](https://github.com/MdaaaaO/conventional-release/commit/3ff7da253f1f06669185f5e7862dc5c771d73ecb))
+
+
+### Tests
+
+* changelog shape, version files and the release flow on throwaway repos ([a53ac38](https://github.com/MdaaaaO/conventional-release/commit/a53ac38a4933d831520baa8b35e332ab4d1ee91b))
+
+
+### Build System
+
+* make targets for ci, build and release ([29cad9f](https://github.com/MdaaaaO/conventional-release/commit/29cad9fe7e452941b3bee0dc9eb8ed91b6e58c57))
+
+
+### CI
+
+* reusable tag and pr-title workflows; the project releases itself to PyPI ([a23b86b](https://github.com/MdaaaaO/conventional-release/commit/a23b86bcb75c1ece841d201128ee123887aacd45))
+* pin astral-sh/setup-uv to v10.2.0 ([#1](https://github.com/MdaaaaO/conventional-release/issues/1)) ([9ba8212](https://github.com/MdaaaaO/conventional-release/commit/9ba821294387fe13173dbfb50cae0ebc731b26dc))
+* claude review on pull requests ([#2](https://github.com/MdaaaaO/conventional-release/issues/2)) ([dbacb35](https://github.com/MdaaaaO/conventional-release/commit/dbacb3580efb2a94378b7b71db0c92cdf56a8b68))

conventional_release-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,23 @@
+# Contributing
+
+Thanks for helping. The short version:
+
+- **Open an issue first** for anything bigger than a typo, so we agree on the change before you write it.
+- **PR titles are [Conventional Commits](https://www.conventionalcommits.org).** PRs are
+  squash-merged, the title becomes the commit, and the commit becomes the changelog line. The
+  `pr-title` check enforces this (`feat(cli): add --json`, `fix: …`, `docs: …`). Put `!` after
+  the type or scope for a breaking change, and explain it in a `BREAKING CHANGE:` footer in the
+  PR description.
+- **`make ci` passes locally** before you push. It runs ruff, `mypy --strict`, pytest with branch
+  coverage, and actionlint. You need [uv](https://docs.astral.sh/uv/). Run `make install` once.
+- An automated Claude review comments on each PR from this repo's branches. It is advisory; a
+  maintainer decides. Maintainers can ask it again after a fix push with `@claude review`.
+- New behaviour comes with a test. The tests build throwaway git repos in `tmp_path`; see
+  `tests/conftest.py`.
+
+## Releasing (maintainers)
+
+`make release` (or `make release ARGS=minor`) opens the `chore(release): X.Y.Z` PR. Squash-merge
+it with the title unchanged. `release.yml` then tags the merge commit, publishes the GitHub
+Release, publishes to TestPyPI and then to PyPI (the `pypi` environment waits for approval), and
+moves the `v0` major tag. `make release-dry` shows what would ship.