Skip to content

Commit 4368158

Browse files
veithlyveithly
authored
Merge pull request #142 from veithly/feat/update-version
feat(ci): add automated publishing workflows for python package
2 parents 1a6f487 + c80904c commit 4368158

File tree

10 files changed

+467
-10
lines changed

10 files changed

+467
-10
lines changed

‎.bumpversion.cfg‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
[bumpversion]
2+
current_version = 0.2.0
3+
commit = True
4+
tag = True
5+
tag_name = v{new_version}
6+
7+
[bumpversion:file:pyproject.toml]
8+
search = version = "{current_version}"
9+
replace = version = "{new_version}"

‎.github/README.md‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
# GitHub Actions Workflows for Spoon Core
2+
3+
This directory contains GitHub Actions workflows for automated testing, building, and publishing of the Spoon AI SDK Python package.
4+
5+
## Workflows Overview
6+
7+
### 1. CI Workflow (`ci.yml`)
8+
- **Trigger**: Push to `main`/`develop` branches, Pull Requests
9+
- **Purpose**: Build package and verify compatibility across Python versions
10+
- **Features**:
11+
- Multi-Python version build verification (3.11, 3.12, 3.13)
12+
- Package build and validation
13+
- Artifact upload for releases
14+
- No testing - focuses on build verification only
15+
16+
### 2. Release Workflow (`release.yml`)
17+
- **Trigger**: Push of version tags (e.g., `v1.2.3`)
18+
- **Purpose**: Automatically publish to PyPI and create GitHub releases
19+
- **Features**:
20+
- Build package distribution
21+
- Upload to PyPI using API token
22+
- Create GitHub release with changelog
23+
24+
### 3. Version Bump Workflow (`version-bump.yml`)
25+
- **Trigger**: Manual workflow dispatch
26+
- **Purpose**: Automated version management and tagging
27+
- **Features**:
28+
- Support for patch/minor/major version bumps
29+
- Custom version input option
30+
- Automatic commit and tag creation
31+
- Push to repository
32+
33+
## Setup Instructions
34+
35+
### 1. PyPI API Token Setup
36+
37+
1. Go to [PyPI](https://pypi.org/) and log in
38+
2. Go to Account Settings → API tokens
39+
3. Create a new API token with scope for your project
40+
4. In your GitHub repository, go to Settings → Secrets and variables → Actions
41+
5. Add a new repository secret named `PYPI_API_TOKEN` with your token value
42+
43+
### 2. Repository Settings
44+
45+
Ensure your repository has the following settings:
46+
47+
- **Actions permissions**: Allow actions to create and approve pull requests
48+
- **Workflow permissions**: Read and write permissions for GITHUB_TOKEN
49+
50+
### 3. Branch Protection (Recommended)
51+
52+
Set up branch protection for `main` branch:
53+
- Require status checks to pass
54+
- Require branches to be up to date
55+
- Include administrators in restrictions
56+
57+
## Usage
58+
59+
### Automatic Release Process
60+
61+
1. **Version Bump**: Use the Version Bump workflow to increment version
62+
- Go to Actions → Version Bump and Tag → Run workflow
63+
- Choose version type (patch/minor/major) or enter custom version
64+
65+
2. **Automatic Publishing**: When a version tag is pushed, the release workflow automatically:
66+
- Builds the package
67+
- Publishes to PyPI
68+
- Creates a GitHub release
69+
70+
### Manual Version Management
71+
72+
If you prefer manual version management:
73+
74+
1. Update version in `pyproject.toml`
75+
2. Commit changes: `git commit -m "Bump version to x.y.z"`
76+
3. Create tag: `git tag vx.y.z`
77+
4. Push: `git push && git push --tags`
78+
79+
## Workflow Details
80+
81+
### CI Workflow
82+
```yaml
83+
# Runs on every push/PR
84+
- Multi-version Python build verification
85+
- Package build and twine check
86+
- Upload build artifacts
87+
- No testing - focuses on build verification only
88+
```
89+
90+
### Release Workflow
91+
```yaml
92+
# Runs on version tags
93+
- Checkout code
94+
- Setup Python 3.11
95+
- Install build tools
96+
- Build package (sdist + wheel)
97+
- Upload to PyPI
98+
- Create GitHub release
99+
```
100+
101+
### Version Bump Workflow
102+
```yaml
103+
# Manual trigger
104+
- Checkout with write permissions
105+
- Install bump2version
106+
- Calculate new version
107+
- Update pyproject.toml
108+
- Commit and tag
109+
- Push changes
110+
```
111+
112+
## Dependencies
113+
114+
The following tools are used in the workflows:
115+
116+
- `build`: Package building
117+
- `twine`: PyPI uploading
118+
- `pytest`: Testing framework
119+
- `pytest-cov`: Coverage reporting
120+
- `pytest-asyncio`: Async test support
121+
- `tox`: Multi-environment testing
122+
- `bump2version`: Version management
123+
124+
## Testing Configuration
125+
126+
The CI workflow uses both pytest and tox for comprehensive testing:
127+
128+
### pytest Configuration
129+
- Located in `tests/pytest.ini`
130+
- Asyncio mode: auto
131+
- Coverage reporting enabled
132+
133+
### tox Configuration
134+
- Located in `tox.ini`
135+
- Supports Python versions: 3.9, 3.10, 3.11, 3.12, 3.13
136+
- Isolated build environments
137+
- Coverage reporting support
138+
139+
## Troubleshooting
140+
141+
### Common Issues
142+
143+
1. **PyPI Upload Fails**
144+
- Check `PYPI_API_TOKEN` secret is set correctly
145+
- Verify token has upload permissions for the project
146+
147+
2. **Tests Fail**
148+
- Check Python version compatibility (requires >=3.10)
149+
- Ensure all dependencies are in `requirements.txt`
150+
- Verify test configuration in `pytest.ini`
151+
152+
3. **Build Fails**
153+
- Check `pyproject.toml` configuration
154+
- Ensure package structure matches `setuptools` configuration
155+
- Verify Python version compatibility
156+
157+
### Debug Mode
158+
159+
To debug workflow issues:
160+
1. Go to Actions tab in GitHub
161+
2. Select the failed workflow run
162+
3. Check logs for each step
163+
4. Use `debug` logging level if available
164+
165+
## Contributing
166+
167+
When contributing to the workflows:
168+
169+
1. Test changes on a feature branch first
170+
2. Update this documentation if workflows change
171+
3. Ensure backward compatibility
172+
4. Follow GitHub Actions best practices
173+
174+
## Security Notes
175+
176+
- Never commit secrets to the repository
177+
- Use repository secrets for sensitive data
178+
- Regularly rotate API tokens
179+
- Limit token scopes to minimum required permissions

‎.github/workflows/ci.yml‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [ main, develop ]
6+
pull_request:
7+
branches: [ main, develop ]
8+
9+
jobs:
10+
build:
11+
runs-on: ubuntu-latest
12+
strategy:
13+
matrix:
14+
python-version: ['3.11', '3.12', '3.13']
15+
16+
steps:
17+
- name: Checkout code
18+
uses: actions/checkout@v4
19+
20+
- name: Set up Python ${{ matrix.python-version }}
21+
uses: actions/setup-python@v4
22+
with:
23+
python-version: ${{ matrix.python-version }}
24+
25+
- name: Install build dependencies
26+
run: |
27+
python -m pip install --upgrade pip
28+
pip install build twine
29+
30+
- name: Build package
31+
run: python -m build
32+
33+
- name: Check package
34+
run: twine check dist/*
35+
36+
- name: Upload build artifacts
37+
uses: actions/upload-artifact@v3
38+
with:
39+
name: python-package-distributions
40+
path: dist/

‎.github/workflows/release.yml‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
name: Release to PyPI
2+
3+
on:
4+
push:
5+
tags:
6+
- 'v*.*.*'
7+
8+
jobs:
9+
release:
10+
runs-on: ubuntu-latest
11+
12+
steps:
13+
- name: Checkout code
14+
uses: actions/checkout@v4
15+
16+
- name: Set up Python
17+
uses: actions/setup-python@v4
18+
with:
19+
python-version: '3.11'
20+
21+
- name: Install dependencies
22+
run: |
23+
python -m pip install --upgrade pip
24+
pip install build twine
25+
26+
- name: Build package
27+
run: python -m build
28+
29+
- name: Publish to PyPI
30+
env:
31+
TWINE_USERNAME: __token__
32+
TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
33+
run: |
34+
twine upload dist/*
35+
36+
- name: Create GitHub Release
37+
uses: actions/create-release@v1
38+
env:
39+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
40+
with:
41+
tag_name: ${{ github.ref }}
42+
release_name: Release ${{ github.ref }}
43+
body: |
44+
Automatic release created for version ${{ github.ref_name }}
45+
46+
## Changes
47+
- Version bump to ${{ github.ref_name }}
48+
- Automatic PyPI publication for spoon-ai-sdk
49+
draft: false
50+
prerelease: false

‎.github/workflows/version-bump.yml‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
name: Version Bump and Tag
2+
3+
on:
4+
workflow_dispatch:
5+
inputs:
6+
version_type:
7+
description: 'Version bump type'
8+
required: true
9+
default: 'patch'
10+
type: choice
11+
options:
12+
- patch
13+
- minor
14+
- major
15+
custom_version:
16+
description: 'Custom version (optional, overrides version_type)'
17+
required: false
18+
type: string
19+
20+
jobs:
21+
version-bump:
22+
runs-on: ubuntu-latest
23+
24+
steps:
25+
- name: Checkout code
26+
uses: actions/checkout@v4
27+
with:
28+
token: ${{ secrets.GITHUB_TOKEN }}
29+
30+
- name: Set up Python
31+
uses: actions/setup-python@v4
32+
with:
33+
python-version: '3.11'
34+
35+
- name: Install dependencies
36+
run: |
37+
python -m pip install --upgrade pip
38+
pip install bump2version
39+
40+
- name: Configure Git
41+
run: |
42+
git config --local user.email "action@github.com"
43+
git config --local user.name "GitHub Action"
44+
45+
- name: Bump version
46+
id: bump
47+
run: |
48+
if [ -n "${{ github.event.inputs.custom_version }}" ]; then
49+
# Use custom version
50+
NEW_VERSION="${{ github.event.inputs.custom_version }}"
51+
echo "Using custom version: $NEW_VERSION"
52+
else
53+
# Use version type bump
54+
case "${{ github.event.inputs.version_type }}" in
55+
patch)
56+
bump2version patch --dry-run --list | grep new_version | cut -d'=' -f2
57+
;;
58+
minor)
59+
bump2version minor --dry-run --list | grep new_version | cut -d'=' -f2
60+
;;
61+
major)
62+
bump2version major --dry-run --list | grep new_version | cut -d'=' -f2
63+
;;
64+
esac
65+
fi
66+
67+
# Extract current version from pyproject.toml
68+
CURRENT_VERSION=$(grep '^version =' pyproject.toml | sed 's/version = "\(.*\)"/\1/')
69+
70+
if [ -n "${{ github.event.inputs.custom_version }}" ]; then
71+
NEW_VERSION="${{ github.event.inputs.custom_version }}"
72+
else
73+
# Calculate new version based on type
74+
IFS='.' read -ra VERSION_PARTS <<< "$CURRENT_VERSION"
75+
case "${{ github.event.inputs.version_type }}" in
76+
patch)
77+
NEW_VERSION="${VERSION_PARTS[0]}.${VERSION_PARTS[1]}.$((VERSION_PARTS[2] + 1))"
78+
;;
79+
minor)
80+
NEW_VERSION="${VERSION_PARTS[0]}.$((VERSION_PARTS[1] + 1)).0"
81+
;;
82+
major)
83+
NEW_VERSION="$((VERSION_PARTS[0] + 1)).0.0"
84+
;;
85+
esac
86+
fi
87+
88+
echo "Current version: $CURRENT_VERSION"
89+
echo "New version: $NEW_VERSION"
90+
echo "new_version=$NEW_VERSION" >> $GITHUB_OUTPUT
91+
92+
# Update pyproject.toml
93+
sed -i "s/version = \"$CURRENT_VERSION\"/version = \"$NEW_VERSION\"/" pyproject.toml
94+
95+
- name: Commit version bump
96+
run: |
97+
git add pyproject.toml
98+
git commit -m "Bump version to ${{ steps.bump.outputs.new_version }}"
99+
100+
- name: Create tag
101+
run: |
102+
git tag "v${{ steps.bump.outputs.new_version }}"
103+
104+
- name: Push changes and tag
105+
run: |
106+
git push origin main
107+
git push origin "v${{ steps.bump.outputs.new_version }}"

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ SpoonOS is a living, evolving agentic operating system. Its SCDF is purpose-buil
5555

5656
### Prerequisites
5757

58-
- Python 3.10+
58+
- Python 3.11+
5959
- pip package manager (or uv as a faster alternative)
6060

6161
```bash

0 commit comments

Comments
 (0)