Skip to content

Commit a94d6a0

Browse files
nicholasadamounicholasadamou
committed
Add PyPI publishing documentation
1 parent 707561b commit a94d6a0

File tree

2 files changed

+185
-0
lines changed

2 files changed

+185
-0
lines changed

‎PUBLISHING.md‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
# Publishing Guide
2+
3+
This guide covers how to publish webgrab to PyPI.
4+
5+
## Prerequisites
6+
7+
1. **PyPI Account**
8+
- Create an account at https://pypi.org
9+
- Create an account at https://test.pypi.org (for testing)
10+
11+
2. **API Tokens**
12+
- Generate an API token on PyPI (Account Settings → API tokens)
13+
- Generate an API token on Test PyPI
14+
- Store tokens in GitHub Secrets:
15+
- `PYPI_API_TOKEN` - Production PyPI token
16+
- `TEST_PYPI_API_TOKEN` - Test PyPI token
17+
18+
3. **GitHub Permissions**
19+
- Ensure you have permission to create releases in the repository
20+
21+
## Manual Publishing
22+
23+
### 1. Prepare for Release
24+
25+
Update the version in `pyproject.toml`:
26+
27+
```toml
28+
[project]
29+
name = "webgrab"
30+
version = "0.1.1" # Increment this
31+
```
32+
33+
### 2. Build the Package
34+
35+
```bash
36+
# Install build tools
37+
pip install build twine
38+
39+
# Build the package
40+
python -m build
41+
42+
# Check the build
43+
twine check dist/*
44+
```
45+
46+
### 3. Test on Test PyPI (Recommended)
47+
48+
```bash
49+
# Upload to Test PyPI
50+
twine upload --repository testpypi dist/*
51+
52+
# Test installation
53+
pip install --index-url https://test.pypi.org/simple/ webgrab
54+
```
55+
56+
### 4. Publish to PyPI
57+
58+
```bash
59+
# Upload to PyPI
60+
twine upload dist/*
61+
```
62+
63+
## Automated Publishing via GitHub Actions
64+
65+
The recommended approach is to use GitHub Actions for automated publishing.
66+
67+
### Publishing to Test PyPI
68+
69+
Use the manual workflow dispatch:
70+
71+
1. Go to **Actions** → **Publish to PyPI**
72+
2. Click **Run workflow**
73+
3. Check **Publish to Test PyPI instead of PyPI**
74+
4. Click **Run workflow**
75+
76+
### Publishing to Production PyPI
77+
78+
Create a GitHub Release:
79+
80+
1. **Update Version**
81+
```bash
82+
# Update version in pyproject.toml
83+
git add pyproject.toml
84+
git commit -m "Bump version to 0.1.1"
85+
git push
86+
```
87+
88+
2. **Create and Push Tag**
89+
```bash
90+
git tag v0.1.1
91+
git push origin v0.1.1
92+
```
93+
94+
3. **Create GitHub Release**
95+
- Go to **Releases** → **Draft a new release**
96+
- Select the tag you just created (`v0.1.1`)
97+
- Set the release title (e.g., `v0.1.1`)
98+
- Add release notes describing changes
99+
- Click **Publish release**
100+
101+
4. **Automatic Publishing**
102+
- GitHub Actions will automatically:
103+
- Build the package
104+
- Run quality checks
105+
- Publish to PyPI
106+
- Available at: https://pypi.org/project/webgrab/
107+
108+
## Release Checklist
109+
110+
Before creating a release:
111+
112+
- [ ] All tests pass locally (`pytest`)
113+
- [ ] Lint checks pass (`ruff check src/webgrab tests`)
114+
- [ ] GitHub Actions workflows are green
115+
- [ ] Version number updated in `pyproject.toml`
116+
- [ ] CHANGELOG.md updated (if exists)
117+
- [ ] README.md updated if needed
118+
- [ ] All changes committed and pushed
119+
120+
## Versioning
121+
122+
We follow [Semantic Versioning](https://semver.org/):
123+
124+
- **MAJOR** version (1.0.0): Incompatible API changes
125+
- **MINOR** version (0.1.0): Add functionality (backwards compatible)
126+
- **PATCH** version (0.0.1): Bug fixes (backwards compatible)
127+
128+
Examples:
129+
- `0.1.0` → `0.1.1`: Bug fix
130+
- `0.1.0` → `0.2.0`: New feature
131+
- `0.9.0` → `1.0.0`: First stable release
132+
133+
## Troubleshooting
134+
135+
### "File already exists" error
136+
137+
PyPI doesn't allow re-uploading the same version. You must:
138+
1. Increment the version number
139+
2. Rebuild: `python -m build`
140+
3. Upload again
141+
142+
### GitHub Actions fails to publish
143+
144+
Check that:
145+
1. GitHub Secrets are set correctly (`PYPI_API_TOKEN`)
146+
2. The API token has upload permissions
147+
3. The version number doesn't already exist on PyPI
148+
149+
### Package doesn't install correctly
150+
151+
Verify `pyproject.toml` includes:
152+
- Correct package name
153+
- All dependencies
154+
- Correct package paths in `[tool.hatch.build.targets.wheel]`
155+
156+
## Post-Release
157+
158+
After publishing:
159+
160+
1. **Verify Installation**
161+
```bash
162+
pip install webgrab
163+
webgrab --version
164+
```
165+
166+
2. **Update Documentation**
167+
- Update README.md badges if needed
168+
- Update installation instructions
169+
- Announce the release (Twitter, Discord, etc.)
170+
171+
3. **Monitor Issues**
172+
- Watch for issues on GitHub
173+
- Check PyPI download stats
174+
- Respond to user feedback
175+
176+
## Resources
177+
178+
- [PyPI Help](https://pypi.org/help/)
179+
- [Python Packaging Guide](https://packaging.python.org/)
180+
- [Semantic Versioning](https://semver.org/)
181+
- [GitHub Releases](https://docs.github.com/en/repositories/releasing-projects-on-github)

‎README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -221,6 +221,10 @@ The codebase follows these principles:
221221
- Playwright 1.40.0+
222222
- Modern web browser (Chromium via Playwright)
223223

224+
## Publishing
225+
226+
For instructions on publishing webgrab to PyPI, see [PUBLISHING.md](PUBLISHING.md).
227+
224228
## Contributing
225229

226230
Contributions are welcome! Please:

0 commit comments

Comments
 (0)