Skip to content

Commit ec25426

Browse files
prudhommprudhomm
committed
docs: add AGENTS.md with version bump checklist and maintenance guide
- Document complete version bump process (pyproject.toml + __init__.py) - Add checklist to prevent missing files during releases - Include project structure, CI/CD info, and troubleshooting - Provide guidance for AI agents working on the package - Reference common maintenance tasks and environment setup Prevents future version sync issues like the __init__.py oversight.
1 parent cb714a7 commit ec25426

File tree

1 file changed

+203
-0
lines changed

1 file changed

+203
-0
lines changed

‎AGENTS.md‎

Lines changed: 203 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
1+
# AI Agents Guide for Article CLI
2+
3+
This document provides guidance for AI agents working on the article-cli package, including common tasks, version management, and maintenance procedures.
4+
5+
## 🚀 Version Bump Process
6+
7+
When releasing a new version, **ALL** of these files must be updated with the new version number:
8+
9+
### Required Files to Update:
10+
11+
1. **`pyproject.toml`** - Line ~7
12+
```toml
13+
version = "1.0.X"
14+
```
15+
16+
2. **`src/article_cli/__init__.py`** - Line ~11
17+
```python
18+
__version__ = "1.0.X"
19+
```
20+
21+
3. **`CHANGELOG.md`** - Add new version section at top
22+
```markdown
23+
## [1.0.X] - YYYY-MM-DD
24+
### Added/Fixed/Changed
25+
- Description of changes
26+
```
27+
28+
4. **`CHANGELOG.md`** - Update links section at bottom
29+
```markdown
30+
[1.0.X]: https://github.com/feelpp/article.cli/releases/tag/v1.0.X
31+
```
32+
33+
### Version Bump Checklist:
34+
35+
- [ ] Update `pyproject.toml` version
36+
- [ ] Update `src/article_cli/__init__.py` __version__
37+
- [ ] Add new section to `CHANGELOG.md`
38+
- [ ] Update CHANGELOG.md links
39+
- [ ] Commit changes: `git commit -m "chore: bump version to 1.0.X"`
40+
- [ ] Push changes: `git push`
41+
- [ ] Create GitHub release: `gh release create v1.0.X`
42+
- [ ] Verify PyPI publication via trusted publishing
43+
44+
### Semantic Versioning Guide:
45+
46+
- **MAJOR (2.0.0)**: Breaking changes to CLI interface or API
47+
- **MINOR (1.1.0)**: New features, backwards compatible
48+
- **PATCH (1.0.1)**: Bug fixes, backwards compatible
49+
50+
## 🧪 Testing Before Release
51+
52+
Always run these checks before releasing:
53+
54+
```bash
55+
# Code quality checks
56+
black --check src/
57+
flake8 src/
58+
mypy src/
59+
60+
# Local functionality test
61+
pip install -e .
62+
article-cli --version
63+
article-cli --help
64+
article-cli config show
65+
```
66+
67+
## 📁 Project Structure
68+
69+
```
70+
article.cli/
71+
├── .github/workflows/ # CI/CD automation
72+
│ ├── ci.yml # Build, test, lint pipeline
73+
│ └── publish.yml # PyPI publishing (trusted)
74+
├── src/article_cli/ # Python package source
75+
│ ├── __init__.py # Package version & exports
76+
│ ├── cli.py # Main CLI interface
77+
│ ├── config.py # Configuration management
78+
│ ├── zotero.py # Zotero API integration
79+
│ └── git_manager.py # Git operations
80+
├── tests/ # Test suite
81+
├── pyproject.toml # Package configuration
82+
├── CHANGELOG.md # Release history
83+
├── README.md # User documentation
84+
├── DEVELOPMENT.md # Developer guide
85+
├── MIGRATION.md # Migration from old scripts
86+
├── PYPI_SETUP.md # PyPI publishing setup
87+
└── AGENTS.md # This file
88+
```
89+
90+
## 🔧 Common Maintenance Tasks
91+
92+
### Adding New Commands
93+
94+
1. Add command parser in `src/article_cli/cli.py`
95+
2. Implement command handler function
96+
3. Add to `create_parser()` subcommands
97+
4. Update help text and documentation
98+
5. Add tests for new functionality
99+
100+
### Updating Dependencies
101+
102+
1. Update `pyproject.toml` dependencies section
103+
2. Test with different Python versions (3.8-3.12)
104+
3. Update CI if needed
105+
4. Document any breaking changes
106+
107+
### Configuration Changes
108+
109+
1. Update `src/article_cli/config.py` for new settings
110+
2. Update sample config generation
111+
3. Update documentation examples
112+
4. Maintain backward compatibility
113+
114+
## 🏗️ CI/CD Pipeline
115+
116+
### Automated Workflows:
117+
118+
1. **Build and Test** (`ci.yml`):
119+
- Triggered on: push to main/develop, pull requests
120+
- Tests: Python 3.8, 3.9, 3.10, 3.11, 3.12
121+
- Checks: Black, flake8, mypy, CLI functionality
122+
- Artifacts: Built package for distribution
123+
124+
2. **Publish to PyPI** (`publish.yml`):
125+
- Triggered on: GitHub release published
126+
- Uses: Trusted publishing (no tokens required)
127+
- Publishes to: https://pypi.org/project/article-cli/
128+
129+
### Manual Release Process:
130+
131+
```bash
132+
# 1. Prepare release
133+
git checkout main
134+
git pull origin main
135+
136+
# 2. Bump version (update all files listed above)
137+
# 3. Commit and push
138+
git add -A
139+
git commit -m "chore: bump version to 1.0.X"
140+
git push
141+
142+
# 4. Create GitHub release (triggers PyPI publishing)
143+
gh release create v1.0.X --title "v1.0.X - Description" --notes "Release notes"
144+
```
145+
146+
## 🔍 Troubleshooting
147+
148+
### Common Issues:
149+
150+
1. **PyPI Publishing Fails**:
151+
- Check trusted publishing configuration on PyPI
152+
- Verify GitHub repository settings
153+
- Ensure version number is incremented
154+
155+
2. **Version Mismatch**:
156+
- Ensure `pyproject.toml` and `__init__.py` versions match
157+
- Reinstall package locally: `pip install -e .`
158+
- Test: `article-cli --version`
159+
160+
3. **CI Failures**:
161+
- Check code formatting: `black src/`
162+
- Check linting: `flake8 src/`
163+
- Check types: `mypy src/`
164+
- Update GitHub Actions if deprecated
165+
166+
### Environment Setup:
167+
168+
```bash
169+
# Fresh development environment
170+
cd /Users/prudhomm/Devel/Articles/article.cli
171+
python3 -m venv venv
172+
source venv/bin/activate
173+
pip install --upgrade pip
174+
pip install -e .
175+
pip install black flake8 mypy types-requests pytest
176+
```
177+
178+
## 📚 Documentation Locations
179+
180+
- **User Guide**: `README.md`
181+
- **Development**: `DEVELOPMENT.md`
182+
- **Migration**: `MIGRATION.md`
183+
- **PyPI Setup**: `PYPI_SETUP.md`
184+
- **Release History**: `CHANGELOG.md`
185+
- **This Guide**: `AGENTS.md`
186+
187+
## 🎯 Default Configuration Values
188+
189+
- **Default Zotero Group ID**: `4678293` (for article.template)
190+
- **Default Output File**: `references.bib`
191+
- **Default Branch**: `main`
192+
- **Python Support**: 3.8 - 3.12
193+
194+
## 🔗 Important Links
195+
196+
- **GitHub Repository**: https://github.com/feelpp/article.cli
197+
- **PyPI Package**: https://pypi.org/project/article-cli/
198+
- **CI/CD Actions**: https://github.com/feelpp/article.cli/actions
199+
- **PyPI Trusted Publishing**: https://pypi.org/manage/project/article-cli/settings/publishing/
200+
201+
---
202+
203+
**Remember**: Always test locally before releasing, and ensure all version-related files are updated consistently!

0 commit comments

Comments
 (0)