Skip to content

Commit 1391e55

Browse files
lyndonbautolyndonbauto
committed
Add PyPI release workflow and maintainer docs.
Trusted publishing via release.yml on v* tags; documents setup in RELEASING.md and updates README for pip install.
1 parent b16ab95 commit 1391e55

4 files changed

Lines changed: 211 additions & 12 deletions

File tree

‎.github/workflows/release.yml‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# Build and publish to PyPI on version tags (v0.0.1, v0.0.2, …).
2+
# Requires PyPI trusted publishing + GitHub environment "pypi" — see RELEASING.md.
3+
name: Release
4+
5+
on:
6+
push:
7+
tags:
8+
- "v*"
9+
10+
permissions:
11+
contents: read
12+
13+
jobs:
14+
test:
15+
name: Tests before release
16+
runs-on: ubuntu-latest
17+
timeout-minutes: 25
18+
steps:
19+
- name: Checkout
20+
uses: actions/checkout@v4
21+
22+
- name: Set up Python
23+
uses: actions/setup-python@v5
24+
with:
25+
python-version: "3.11"
26+
cache: pip
27+
cache-dependency-path: pyproject.toml
28+
29+
- name: Install dependencies
30+
run: python -m pip install --upgrade pip && pip install -e ".[dev]"
31+
32+
- name: Run unit tests
33+
run: pytest -m "not aerospike" -v --tb=short
34+
35+
- name: Start Aerospike CE (Docker)
36+
run: |
37+
chmod +x scripts/start_aerospike_ce.sh scripts/stop_aerospike_ce.sh
38+
./scripts/start_aerospike_ce.sh
39+
40+
- name: Run integration tests
41+
run: |
42+
set -a
43+
source .aerospike-ci.env
44+
set +a
45+
pytest -m aerospike -v --tb=short
46+
47+
- name: Stop Aerospike CE
48+
if: always()
49+
run: ./scripts/stop_aerospike_ce.sh
50+
51+
build:
52+
name: Build distributions
53+
needs: test
54+
runs-on: ubuntu-latest
55+
steps:
56+
- name: Checkout
57+
uses: actions/checkout@v4
58+
59+
- name: Verify tag matches pyproject.toml version
60+
run: |
61+
tag="${GITHUB_REF#refs/tags/}"
62+
expected="${tag#v}"
63+
actual="$(grep -E '^version = ' pyproject.toml | sed -E 's/^version = "(.*)"/\1/')"
64+
if [ "$expected" != "$actual" ]; then
65+
echo "Tag $tag implies version $expected but pyproject.toml has $actual"
66+
exit 1
67+
fi
68+
69+
- name: Set up Python
70+
uses: actions/setup-python@v5
71+
with:
72+
python-version: "3.11"
73+
74+
- name: Build sdist and wheel
75+
run: python -m pip install build && python -m build
76+
77+
- name: Upload distributions
78+
uses: actions/upload-artifact@v4
79+
with:
80+
name: dist
81+
path: dist/
82+
83+
publish:
84+
name: Publish to PyPI
85+
needs: build
86+
runs-on: ubuntu-latest
87+
environment:
88+
name: pypi
89+
url: https://pypi.org/p/adk-aerospike
90+
permissions:
91+
id-token: write
92+
steps:
93+
- name: Download distributions
94+
uses: actions/download-artifact@v4
95+
with:
96+
name: dist
97+
path: dist/
98+
99+
- name: Publish to PyPI
100+
uses: pypa/gh-action-pypi-publish@release/v1

‎CHANGELOG.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [0.0.1] - 2026-05-27
9+
10+
### Added
11+
12+
- Initial PyPI release.
13+
- `AerospikeSessionService`, `AerospikeArtifactService`, and `AerospikeMemoryService` for Google ADK 2.x.
14+
- `aerospike://` URI support via `adk_aerospike.register()`.
15+
- Chunked session records, server-side lexical memory search, and composite tenant indexes.
16+
17+
[0.0.1]: https://github.com/aerospike-community/adk-aerospike/releases/tag/v0.0.1

‎README.md‎

Lines changed: 10 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -41,28 +41,26 @@ registration so the `adk` CLI can use Aerospike directly:
4141
- **No AI/ML dependency.** Memory is a storage backend, not an embedding
4242
pipeline — no embedder to wire up, no model to host.
4343

44-
## Current Install
44+
## Install
4545

46-
**Ensure your python version is 11 before proceeding.**
4746
```bash
48-
python -m venv .venv
49-
source .venv/bin/activate # On Windows: .venv\Scripts\activate
50-
pip install -e .
51-
52-
# To test:
53-
python -c "from adk_aerospike import AerospikeSessionService; print('ok')"
54-
# Should print ok below.
47+
pip install adk-aerospike
5548
```
5649

5750
Requires Python 3.11+ and Aerospike Database 7.x or 8.x (Community or Enterprise).
5851

59-
## Future Install
52+
### Development install
53+
54+
From a clone of this repository (Python 3.11+):
6055

6156
```bash
62-
pip install adk-aerospike
57+
python -m venv .venv
58+
source .venv/bin/activate # Windows: .venv\Scripts\activate
59+
pip install -e ".[dev]"
60+
python -c "from adk_aerospike import AerospikeSessionService; print('ok')"
6361
```
6462

65-
Requires Python 3.11+ and Aerospike Database 7.x or 8.x (Community or Enterprise).
63+
Release process: [RELEASING.md](RELEASING.md).
6664

6765
## Quick start
6866

‎RELEASING.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# Releasing adk-aerospike to PyPI
2+
3+
Automated via [`.github/workflows/release.yml`](.github/workflows/release.yml): push a tag `vX.Y.Z` that matches `version` in `pyproject.toml` and `__version__` in `src/adk_aerospike/__init__.py`.
4+
5+
## One-time setup (maintainers)
6+
7+
### 1. PyPI trusted publisher
8+
9+
Use a PyPI account that can create projects for the Aerospike org (or register a **pending** publisher before the project exists).
10+
11+
1. Sign in at https://pypi.org/manage/account/publishing/
12+
2. **Add a new pending publisher** (first release) or **Add a new publisher** (after the project exists).
13+
3. Set:
14+
| Field | Value |
15+
| --- | --- |
16+
| PyPI project name | `adk-aerospike` |
17+
| Owner | `aerospike-community` |
18+
| Repository name | `adk-aerospike` |
19+
| Workflow name | `release.yml` |
20+
| Environment name | `pypi` |
21+
22+
The workflow filename is the basename only (`release.yml`), not `.github/workflows/release.yml`.
23+
24+
After the first successful publish, the pending publisher becomes a normal project publisher.
25+
26+
### 2. GitHub `pypi` environment
27+
28+
In https://github.com/aerospike-community/adk-aerospike/settings/environments:
29+
30+
1. **New environment** named `pypi` (must match PyPI’s environment name).
31+
2. Recommended protection rules:
32+
- **Required reviewers** — one or two release approvers.
33+
- **Deployment branches** — only `main` (tags are evaluated against the commit they point at; restricting branches still limits who can trigger protected workflows from non-standard refs).
34+
3. Under **Environment secrets** — none needed for trusted publishing (OIDC replaces API tokens).
35+
36+
### 3. Optional: TestPyPI dry run
37+
38+
1. Register at https://test.pypi.org/
39+
2. Add another trusted publisher with the same owner/repo/workflow, or use a separate `testpypi` workflow and environment.
40+
3. Publish manually once, then smoke-test: `pip install -i https://test.pypi.org/simple/ adk-aerospike`
41+
42+
## Cut a release
43+
44+
1. Bump version in **both** `pyproject.toml` and `src/adk_aerospike/__init__.py`.
45+
2. Update `CHANGELOG.md`.
46+
3. Merge to `main`.
47+
4. Tag and push:
48+
49+
```bash
50+
git tag v0.0.1
51+
git push origin v0.0.1
52+
```
53+
54+
5. In GitHub Actions, open the **Release** workflow run; approve the **pypi** environment deployment if reviewers are configured.
55+
6. Confirm https://pypi.org/project/adk-aerospike/ shows the new version.
56+
7. Smoke test from a clean venv:
57+
58+
```bash
59+
pip install "adk-aerospike==0.0.1"
60+
python -c "import adk_aerospike; print(adk_aerospike.__version__)"
61+
```
62+
63+
8. Optional: create a GitHub Release with notes from `CHANGELOG.md`:
64+
65+
```bash
66+
gh release create v0.0.1 --notes-file CHANGELOG.md
67+
```
68+
69+
## Local build check (no upload)
70+
71+
```bash
72+
python -m pip install build
73+
python -m build
74+
pip install dist/adk_aerospike-*.whl
75+
```
76+
77+
## Troubleshooting
78+
79+
| Symptom | Likely cause |
80+
| --- | --- |
81+
| Publish job fails immediately on OIDC | Trusted publisher owner/repo/workflow/environment mismatch |
82+
| “File already exists” on upload | Version not bumped; PyPI versions are immutable |
83+
| Tag/job fails at version check | Tag `v0.0.2` but `pyproject.toml` still `0.0.1` |
84+
| Environment never appears | Workflow must reference `environment: name: pypi` on the publish job |

0 commit comments

Comments
 (0)