Skip to content

Commit 76b34c8

Browse files
mattkanwishermattkanwisher
authored
Merge pull request #2 from TensorFleet/rename-transport
rename gz_transport_py to gz_transport
2 parents 1a13562 + 18574f4 commit 76b34c8

31 files changed

Lines changed: 1075 additions & 1782 deletions

‎.github/RELEASE_GUIDE.md‎

Lines changed: 211 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,211 @@
1+
# Release Guide for easy-drone
2+
3+
This guide explains how to publish the easy-drone package to PyPI using GitHub Actions.
4+
5+
## Prerequisites
6+
7+
### 1. PyPI Account Setup
8+
9+
1. Create accounts on:
10+
- [PyPI](https://pypi.org/account/register/) (for production releases)
11+
- [Test PyPI](https://test.pypi.org/account/register/) (for testing)
12+
13+
2. Create API tokens:
14+
- **PyPI**: Go to [Account Settings → API Tokens](https://pypi.org/manage/account/token/)
15+
- **Test PyPI**: Go to [Account Settings → API Tokens](https://test.pypi.org/manage/account/token/)
16+
- Create a token with "Upload packages" scope
17+
- Save the tokens securely (they're only shown once!)
18+
19+
### 2. GitHub Secrets Setup
20+
21+
Add the following secrets to your GitHub repository:
22+
23+
1. Go to your repository → Settings → Secrets and variables → Actions
24+
2. Add two secrets:
25+
- `PYPI_API_TOKEN`: Your PyPI API token
26+
- `TEST_PYPI_API_TOKEN`: Your Test PyPI API token
27+
28+
**How to add:**
29+
- Click "New repository secret"
30+
- Name: `PYPI_API_TOKEN`
31+
- Value: `pypi-...` (your full token starting with `pypi-`)
32+
- Click "Add secret"
33+
34+
## Workflows
35+
36+
The project includes three GitHub Actions workflows:
37+
38+
### 1. Test Workflow (`test.yml`)
39+
**Trigger**: Push or PR to main/master/develop branches
40+
41+
**What it does**:
42+
- Tests installation on Ubuntu, macOS, and Windows
43+
- Tests Python versions 3.8, 3.9, 3.10, 3.11, 3.12
44+
- Verifies imports work correctly
45+
- Runs verification script
46+
- Builds package and checks it with twine
47+
48+
### 2. Lint Workflow (`lint.yml`)
49+
**Trigger**: Push or PR to main/master/develop branches
50+
51+
**What it does**:
52+
- Checks code formatting with black
53+
- Checks import sorting with isort
54+
- Runs flake8 linting
55+
- All checks continue on error (non-blocking)
56+
57+
### 3. Publish Workflow (`publish.yml`)
58+
**Trigger**:
59+
- Automatically on GitHub Release
60+
- Manually via workflow_dispatch
61+
62+
**What it does**:
63+
- Builds the package (wheel and source distribution)
64+
- Checks package with twine
65+
- Publishes to PyPI or Test PyPI
66+
67+
## Release Process
68+
69+
### Option 1: Automatic Release (Recommended)
70+
71+
#### Step 1: Update Version
72+
Edit `setup.py` and `pyproject.toml`:
73+
```python
74+
version="0.1.1" # Increment version
75+
```
76+
77+
#### Step 2: Commit and Push
78+
```bash
79+
git add setup.py pyproject.toml
80+
git commit -m "Bump version to 0.1.1"
81+
git push origin main
82+
```
83+
84+
#### Step 3: Create GitHub Release
85+
1. Go to your repository → Releases → "Draft a new release"
86+
2. Click "Choose a tag" → Type new tag (e.g., `v0.1.1`) → "Create new tag"
87+
3. Release title: `v0.1.1` or `Release 0.1.1`
88+
4. Description: List changes, new features, bug fixes
89+
5. Click "Publish release"
90+
91+
**The workflow will automatically**:
92+
- Build the package
93+
- Publish to PyPI
94+
- Make it available via `pip install easy-drone`
95+
96+
### Option 2: Manual Testing with Test PyPI
97+
98+
Use this to test the release process before publishing to production PyPI.
99+
100+
#### Step 1: Manual Workflow Trigger
101+
1. Go to Actions → "Publish to PyPI" workflow
102+
2. Click "Run workflow"
103+
3. Select branch (usually `main`)
104+
4. Choose "testpypi" from dropdown
105+
5. Click "Run workflow"
106+
107+
#### Step 2: Test Installation
108+
```bash
109+
# Install from Test PyPI
110+
pip install --index-url https://test.pypi.org/simple/ \
111+
--extra-index-url https://pypi.org/simple/ \
112+
easy-drone
113+
114+
# Test it works
115+
python -c "from gz_transport import Node; print('Success!')"
116+
```
117+
118+
#### Step 3: If successful, publish to PyPI
119+
1. Run workflow again
120+
2. Choose "pypi" from dropdown
121+
3. Or create a GitHub Release (automatic)
122+
123+
## Version Numbering
124+
125+
Follow [Semantic Versioning](https://semver.org/):
126+
- `MAJOR.MINOR.PATCH` (e.g., `1.2.3`)
127+
- **MAJOR**: Incompatible API changes
128+
- **MINOR**: New features, backward compatible
129+
- **PATCH**: Bug fixes, backward compatible
130+
131+
Examples:
132+
- `0.1.0` → `0.1.1`: Bug fix
133+
- `0.1.0` → `0.2.0`: New feature
134+
- `0.9.0` → `1.0.0`: First stable release
135+
136+
## Checklist Before Release
137+
138+
- [ ] Version updated in `setup.py` and `pyproject.toml`
139+
- [ ] `CHANGES.md` or changelog updated
140+
- [ ] All tests passing (check Actions tab)
141+
- [ ] Documentation updated if needed
142+
- [ ] Committed and pushed to main branch
143+
- [ ] Created GitHub release with tag
144+
145+
## Common Issues
146+
147+
### Issue: "Invalid or expired token"
148+
**Solution**: Generate a new API token on PyPI and update GitHub secret
149+
150+
### Issue: "File already exists"
151+
**Solution**: You've already published this version. Increment version number.
152+
153+
### Issue: "Workflow fails to publish"
154+
**Solution**:
155+
- Check GitHub Actions logs
156+
- Verify secrets are set correctly
157+
- Ensure version in setup.py matches tag (without 'v' prefix)
158+
159+
### Issue: "Package not found after publishing"
160+
**Solution**:
161+
- Wait 5-10 minutes for PyPI to index
162+
- Check [https://pypi.org/project/easy-drone/](https://pypi.org/project/easy-drone/)
163+
164+
## After Publishing
165+
166+
### Update Installation Instructions
167+
Users can now install with:
168+
```bash
169+
pip install easy-drone
170+
171+
# With optional features
172+
pip install easy-drone[zenoh]
173+
pip install easy-drone[yolo]
174+
pip install easy-drone[all]
175+
```
176+
177+
### Announce Release
178+
- Update README badges (if any)
179+
- Post announcement (social media, forums, etc.)
180+
- Notify users of changes
181+
182+
## Workflow Files
183+
184+
The workflows are located in `.github/workflows/`:
185+
- `publish.yml` - Publishing to PyPI
186+
- `test.yml` - Testing and verification
187+
- `lint.yml` - Code quality checks
188+
189+
## Security Notes
190+
191+
- **Never** commit API tokens to the repository
192+
- Use GitHub Secrets for all sensitive data
193+
- Tokens should have minimal required permissions
194+
- Rotate tokens periodically
195+
- Use trusted publishing when possible (PyPI supports this)
196+
197+
## Trusted Publishing (Advanced)
198+
199+
For even more security, you can set up [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) which doesn't require API tokens. The workflow already supports this with the `id-token: write` permission.
200+
201+
## Support
202+
203+
For issues with:
204+
- **GitHub Actions**: Check the Actions tab for logs
205+
- **PyPI Publishing**: See [PyPI Help](https://pypi.org/help/)
206+
- **Package Issues**: Open an issue on GitHub
207+
208+
---
209+
210+
**Happy Releasing!** 🚀
211+

‎.github/SETUP_CHECKLIST.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
# GitHub Actions Setup Checklist
2+
3+
Quick checklist to get your GitHub workflows up and running.
4+
5+
## ✅ Immediate Setup (Required for Publishing)
6+
7+
### 1. Create PyPI Accounts
8+
- [ ] Sign up at [PyPI.org](https://pypi.org/account/register/)
9+
- [ ] Sign up at [Test PyPI](https://test.pypi.org/account/register/)
10+
- [ ] Verify email addresses
11+
12+
### 2. Generate API Tokens
13+
- [ ] PyPI: [Account Settings → API Tokens](https://pypi.org/manage/account/token/)
14+
- Create token with "Upload packages" scope
15+
- Save token securely
16+
- [ ] Test PyPI: [Account Settings → API Tokens](https://test.pypi.org/manage/account/token/)
17+
- Create token with "Upload packages" scope
18+
- Save token securely
19+
20+
### 3. Add GitHub Secrets
21+
Go to: Repository → Settings → Secrets and variables → Actions
22+
23+
- [ ] Add `PYPI_API_TOKEN`
24+
- Click "New repository secret"
25+
- Name: `PYPI_API_TOKEN`
26+
- Value: Your PyPI token (starts with `pypi-`)
27+
- Click "Add secret"
28+
29+
- [ ] Add `TEST_PYPI_API_TOKEN`
30+
- Click "New repository secret"
31+
- Name: `TEST_PYPI_API_TOKEN`
32+
- Value: Your Test PyPI token (starts with `pypi-`)
33+
- Click "Add secret"
34+
35+
## ✅ Optional Setup (Recommended)
36+
37+
### 4. Configure Branch Protection
38+
Go to: Repository → Settings → Branches → Add rule
39+
40+
- [ ] Branch name pattern: `main` (or `master`)
41+
- [ ] Require status checks to pass before merging
42+
- [ ] Select "Tests" workflow
43+
- [ ] Require pull request reviews before merging
44+
- [ ] Enable "Automatically delete head branches"
45+
46+
### 5. Add Repository Labels
47+
Go to: Repository → Issues → Labels
48+
49+
Add these labels for Release Drafter:
50+
- [ ] `feature` (color: #0e8a16) - New features
51+
- [ ] `enhancement` (color: #84b6eb) - Improvements
52+
- [ ] `bug` (color: #d73a4a) - Bug reports
53+
- [ ] `fix` (color: #d73a4a) - Bug fixes
54+
- [ ] `documentation` (color: #0075ca) - Documentation
55+
- [ ] `docs` (color: #0075ca) - Docs alias
56+
- [ ] `chore` (color: #fef2c0) - Maintenance
57+
- [ ] `maintenance` (color: #fef2c0) - Maintenance alias
58+
- [ ] `major` (color: #b60205) - Major version bump
59+
- [ ] `minor` (color: #fbca04) - Minor version bump
60+
- [ ] `patch` (color: #c2e0c6) - Patch version bump
61+
62+
### 6. Enable GitHub Actions
63+
Go to: Repository → Settings → Actions → General
64+
65+
- [ ] "Allow all actions and reusable workflows" (or select allowed)
66+
- [ ] Workflow permissions: "Read and write permissions"
67+
- [ ] Enable "Allow GitHub Actions to create and approve pull requests"
68+
69+
### 7. Configure Release Drafter Permissions
70+
Go to: Repository → Settings → Actions → General → Workflow permissions
71+
72+
- [ ] Select "Read and write permissions"
73+
74+
## ✅ Testing Workflows
75+
76+
### 8. Test Installation
77+
- [ ] Push code to `main` branch
78+
- [ ] Check Actions tab - "Tests" workflow should run
79+
- [ ] Verify all jobs pass (Ubuntu, macOS, Windows)
80+
- [ ] Check "Lint" workflow runs successfully
81+
82+
### 9. Test Publishing (Test PyPI)
83+
- [ ] Go to Actions → "Publish to PyPI"
84+
- [ ] Click "Run workflow"
85+
- [ ] Select branch: `main`
86+
- [ ] Choose: `testpypi`
87+
- [ ] Click "Run workflow"
88+
- [ ] Wait for completion
89+
- [ ] Test installation:
90+
```bash
91+
pip install --index-url https://test.pypi.org/simple/ \
92+
--extra-index-url https://pypi.org/simple/ \
93+
easy-drone
94+
```
95+
96+
### 10. Test Release Drafter
97+
- [ ] Create a test branch
98+
- [ ] Make a small change
99+
- [ ] Create a Pull Request
100+
- [ ] Add a label (e.g., `feature`)
101+
- [ ] Merge the PR
102+
- [ ] Go to Releases → Check for draft release
103+
- [ ] Verify release notes are generated
104+
105+
## ✅ Production Release
106+
107+
### 11. First Production Release
108+
- [ ] Update version in `setup.py`: `version="0.1.0"`
109+
- [ ] Update version in `pyproject.toml`: `version = "0.1.0"`
110+
- [ ] Update `CHANGES.md` with release notes
111+
- [ ] Commit and push:
112+
```bash
113+
git add setup.py pyproject.toml CHANGES.md
114+
git commit -m "Prepare release 0.1.0"
115+
git push origin main
116+
```
117+
- [ ] Create GitHub Release:
118+
- Go to Releases → "Draft a new release"
119+
- Tag: `v0.1.0` (create new)
120+
- Title: `v0.1.0` or `Release 0.1.0`
121+
- Description: Copy from CHANGES.md
122+
- Click "Publish release"
123+
- [ ] Wait for "Publish to PyPI" workflow to complete
124+
- [ ] Verify on PyPI: https://pypi.org/project/easy-drone/
125+
- [ ] Test installation:
126+
```bash
127+
pip install easy-drone
128+
python -c "from gz_transport import Node; print('Success!')"
129+
```
130+
131+
## 📝 Quick Reference
132+
133+
### View Workflow Runs
134+
Repository → Actions tab
135+
136+
### Check Workflow Logs
137+
Actions → Select workflow → Click on run → Expand job
138+
139+
### Manually Trigger Workflow
140+
Actions → Select workflow → "Run workflow" button
141+
142+
### Update Secrets
143+
Settings → Secrets and variables → Actions → Edit secret
144+
145+
### Check Package on PyPI
146+
- Production: https://pypi.org/project/easy-drone/
147+
- Test: https://test.pypi.org/project/easy-drone/
148+
149+
## 🆘 Troubleshooting
150+
151+
### Workflow fails with "Invalid token"
152+
➡️ Check that secrets are set correctly in Settings → Secrets
153+
154+
### Workflow fails with "Resource not accessible"
155+
➡️ Check workflow permissions in Settings → Actions → General
156+
157+
### Package not found after publishing
158+
➡️ Wait 5-10 minutes for PyPI to index, then check PyPI project page
159+
160+
### Tests fail on specific platform
161+
➡️ Check workflow logs, may need platform-specific fixes
162+
163+
### Release Drafter not creating releases
164+
➡️ Check workflow permissions include "contents: write"
165+
166+
## 📚 Documentation
167+
168+
- [RELEASE_GUIDE.md](.github/RELEASE_GUIDE.md) - Detailed release process
169+
- [WORKFLOWS_SUMMARY.md](.github/WORKFLOWS_SUMMARY.md) - Workflow details
170+
- [GitHub Actions Docs](https://docs.github.com/en/actions)
171+
- [PyPI Publishing Guide](https://packaging.python.org/tutorials/packaging-projects/)
172+
173+
## ✨ Ready to Release!
174+
175+
Once you've completed this checklist, you're ready to:
176+
1. ✅ Run tests automatically on every push
177+
2. ✅ Maintain code quality with linting
178+
3. ✅ Publish to PyPI with one click
179+
4. ✅ Auto-generate release notes
180+
181+
**Happy Releasing!** 🚀
182+

0 commit comments

Comments
 (0)