From 60f2d25cb77a1794c1289783480dda27fdfd27af Mon Sep 17 00:00:00 2001 From: craftsangjae Date: Mon, 16 Feb 2026 10:14:37 +0900 Subject: [PATCH 1/5] Fix package name references from muvera to muvera-python in docs Co-Authored-By: Claude Opus 4.6 --- .github/workflows/publish.yml | 4 ++-- README.md | 2 +- RELEASE_GUIDE.md | 18 +++++++++--------- 3 files changed, 12 insertions(+), 12 deletions(-) diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 10b1b8c..c0877b8 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -68,7 +68,7 @@ jobs: body: | ## Installation ```bash - pip install muvera==${{ github.ref_name }} + pip install muvera-python==${{ github.ref_name }} ``` - See [PyPI](https://pypi.org/project/muvera/${{ github.ref_name }}/) for full package details. + See [PyPI](https://pypi.org/project/muvera-python/${{ github.ref_name }}/) for full package details. diff --git a/README.md b/README.md index 7a681b8..7947a4f 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ This library wraps the full algorithm behind a **single `Muvera` class** with a ## Installation ```bash -pip install muvera +pip install muvera-python ``` Development install: diff --git a/RELEASE_GUIDE.md b/RELEASE_GUIDE.md index 53d7399..b2e9d8a 100644 --- a/RELEASE_GUIDE.md +++ b/RELEASE_GUIDE.md @@ -1,6 +1,6 @@ # Release Guide -Complete guide for releasing muvera to PyPI and creating GitHub releases. +Complete guide for releasing muvera-python to PyPI and creating GitHub releases. ## 🔧 One-time Setup @@ -10,7 +10,7 @@ Complete guide for releasing muvera to PyPI and creating GitHub releases. 2. Go to Account Settings → Publishing → "Add a new pending publisher" 3. Fill in the form: ``` - PyPI Project Name: muvera + PyPI Project Name: muvera-python Owner: craftsangjae Repository name: muvera-python Workflow name: publish.yml @@ -18,7 +18,7 @@ Complete guide for releasing muvera to PyPI and creating GitHub releases. ``` 4. Click "Add" -**Note**: The project name `muvera` will be reserved. First release will claim it. +**Note**: The project name `muvera-python` will be reserved. First release will claim it. ### 2. TestPyPI (Optional, for testing) @@ -140,11 +140,11 @@ git push origin v0.1.0 ### 📦 Installation ```bash - pip install muvera + pip install muvera-python ``` ### 🔗 Links - - PyPI: https://pypi.org/project/muvera/ + - PyPI: https://pypi.org/project/muvera-python/ - Documentation: https://github.com/craftsangjae/muvera-python - Paper: https://arxiv.org/abs/2405.19504 ``` @@ -174,12 +174,12 @@ Add to `.github/workflows/publish.yml`: # Wait ~2 minutes for PyPI to process # Check PyPI page -open https://pypi.org/project/muvera/ +open https://pypi.org/project/muvera-python/ # Test installation in fresh environment python -m venv test_env source test_env/bin/activate -pip install muvera +pip install muvera-python # Quick test python -c "from muvera import Muvera; print(Muvera.__doc__)" @@ -277,7 +277,7 @@ After tagging: - [ ] GitHub Actions workflow succeeds - [ ] Package appears on PyPI - [ ] GitHub Release created -- [ ] Installation tested (`pip install muvera`) +- [ ] Installation tested (`pip install muvera-python`) - [ ] README updated --- @@ -332,5 +332,5 @@ git push origin "v$VERSION" gh release create "v$VERSION" --generate-notes # Verify -pip install --upgrade muvera +pip install --upgrade muvera-python ``` From 80d98cb322fa8b244b3a31a390651628a02743eb Mon Sep 17 00:00:00 2001 From: craftsangjae Date: Mon, 16 Feb 2026 10:16:18 +0900 Subject: [PATCH 2/5] Add git/PR convention rules to CLAUDE.md --- CLAUDE.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 25e9f45..bf807d3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -18,6 +18,10 @@ No config dataclasses, no encoding-type enums, no manual seed juggling. Just Num **Key use case**: Efficiently encode ColBERT-style multi-vector embeddings for retrieval without specialized infrastructure. +## Git & PR Conventions +- **Do NOT** add `Co-Authored-By` lines to commit messages. +- **Do NOT** add "Generated with Claude Code" or similar attribution to PR descriptions. + ## Development Commands ### Environment Activation From 17091d9fc72eaa09059a5bbe2e3280c5039aef8c Mon Sep 17 00:00:00 2001 From: craftsangjae Date: Mon, 16 Feb 2026 10:18:46 +0900 Subject: [PATCH 3/5] Auto-tag and publish on version bump merged to main --- .github/workflows/publish.yml | 52 +++++++++++++++++++++++++---------- 1 file changed, 37 insertions(+), 15 deletions(-) diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index c0877b8..5ff94c9 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -2,11 +2,35 @@ name: Publish to PyPI on: push: - tags: - - 'v*.*.*' + branches: [main] jobs: + check-version: + runs-on: ubuntu-latest + outputs: + should_release: ${{ steps.check.outputs.should_release }} + version: ${{ steps.check.outputs.version }} + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Check if version tag already exists + id: check + run: | + VERSION=$(grep '^version = ' pyproject.toml | cut -d'"' -f2) + echo "version=$VERSION" >> "$GITHUB_OUTPUT" + if git rev-parse "v$VERSION" >/dev/null 2>&1; then + echo "Tag v$VERSION already exists, skipping release" + echo "should_release=false" >> "$GITHUB_OUTPUT" + else + echo "Tag v$VERSION does not exist, proceeding with release" + echo "should_release=true" >> "$GITHUB_OUTPUT" + fi + test: + needs: check-version + if: needs.check-version.outputs.should_release == 'true' runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 @@ -25,11 +49,12 @@ jobs: run: pytest -v publish: - needs: test + needs: [check-version, test] + if: needs.check-version.outputs.should_release == 'true' runs-on: ubuntu-latest permissions: - id-token: write # Required for OIDC trusted publishing - contents: write # Required for creating GitHub releases + id-token: write + contents: write steps: - uses: actions/checkout@v4 @@ -39,15 +64,11 @@ jobs: with: python-version: "3.11" - - name: Verify tag matches version + - name: Create version tag run: | - TAG_VERSION=${GITHUB_REF#refs/tags/v} - PACKAGE_VERSION=$(grep '^version = ' pyproject.toml | cut -d'"' -f2) - if [ "$TAG_VERSION" != "$PACKAGE_VERSION" ]; then - echo "Error: Tag version ($TAG_VERSION) does not match package version ($PACKAGE_VERSION)" - exit 1 - fi - echo "Version verified: $TAG_VERSION" + VERSION=${{ needs.check-version.outputs.version }} + git tag "v$VERSION" + git push origin "v$VERSION" - name: Install build dependencies run: | @@ -63,12 +84,13 @@ jobs: - name: Create GitHub Release uses: softprops/action-gh-release@v2 with: + tag_name: v${{ needs.check-version.outputs.version }} files: dist/* generate_release_notes: true body: | ## Installation ```bash - pip install muvera-python==${{ github.ref_name }} + pip install muvera-python==${{ needs.check-version.outputs.version }} ``` - See [PyPI](https://pypi.org/project/muvera-python/${{ github.ref_name }}/) for full package details. + See [PyPI](https://pypi.org/project/muvera-python/${{ needs.check-version.outputs.version }}/) for full package details. From f0b7c442f4f0347f2f305d77fe0223c3506e60c8 Mon Sep 17 00:00:00 2001 From: craftsangjae Date: Mon, 16 Feb 2026 10:21:43 +0900 Subject: [PATCH 4/5] Update CLAUDE.md to reflect auto-tag publish workflow --- CLAUDE.md | 39 +++++++++++++++++---------------------- 1 file changed, 17 insertions(+), 22 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index bf807d3..37f0b3c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -68,25 +68,22 @@ python examples/colbert_nanobeir.py ### Deployment -**Tag-based release with OIDC trusted publishing:** +**Version bump → merge → auto-release:** ```bash # 1. Update version in pyproject.toml # version = "0.2.0" -# 2. Commit the version bump -git add pyproject.toml -git commit -m "Bump version to 0.2.0" - -# 3. Create and push tag -git tag v0.2.0 -git push origin v0.2.0 - +# 2. Create PR and merge to main # GitHub Actions will automatically: -# - Run all tests -# - Verify tag matches pyproject.toml version +# - Detect the new version (tag doesn't exist yet) +# - Run full test suite +# - Create git tag v0.2.0 # - Build wheel and sdist -# - Publish to PyPI via OIDC (no API token needed) +# - Publish to PyPI via OIDC +# - Create GitHub Release +# +# If version is unchanged, all release steps are skipped. ``` **Local build (for testing):** @@ -180,26 +177,24 @@ Output dimension: `num_repetitions * 2^num_simhash_projections * projection_dime - Tests example scripts **`.github/workflows/publish.yml`** - PyPI Publishing -- Triggers: Version tags (e.g., `v0.2.0`) -- Verifies tag matches `pyproject.toml` version +- Triggers: Push to main +- Checks if `v{version}` tag already exists; skips release if it does - Runs full test suite -- Builds wheel and source distribution -- Publishes to PyPI using OIDC trusted publishing (no API token needed) +- Creates git tag, builds wheel/sdist, publishes to PyPI via OIDC +- Creates GitHub Release with release notes ### Deployment Policy -**Tag-based releases with OIDC:** -- All releases are triggered by pushing version tags +**Auto-release on version bump:** +- Merging a PR that changes the version in `pyproject.toml` triggers a release +- If the version is unchanged, all release steps are skipped - Uses OpenID Connect (OIDC) for secure, token-free authentication to PyPI -- Automatic version verification prevents mismatched releases **Pre-deployment checklist:** 1. Update `version` in `pyproject.toml` 2. Run tests locally: `pytest` 3. Check code quality: `ruff check . && mypy muvera` -4. Commit: `git commit -m "Bump version to X.Y.Z"` -5. Tag: `git tag vX.Y.Z` -6. Push tag: `git push origin vX.Y.Z` +4. Create PR and merge to main **OIDC Setup (one-time):** 1. Go to [PyPI](https://pypi.org) → Account settings → Publishing From 655291eeaa5201690a747d08f2ca791399bbd059 Mon Sep 17 00:00:00 2001 From: craftsangjae Date: Mon, 16 Feb 2026 10:24:46 +0900 Subject: [PATCH 5/5] version up Signed-off-by: craftsangjae --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 1d99cb1..15bb244 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "muvera-python" -version = "0.1.2" +version = "0.1.3" description = "MuVERA: Multi-Vector Retrieval via Fixed Dimensional Encodings" readme = "README.md" license = "Apache-2.0"