Skip to content

Commit 4b39c3e

Browse files
inntraninntran
committed
feat: Add bumpversion configuration and release process documentation
1 parent c1af395 commit 4b39c3e

6 files changed

Lines changed: 346 additions & 11 deletions

File tree

‎.bumpversion.toml‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
[tool.bumpversion]
2+
current_version = "0.0.1"
3+
parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
4+
serialize = ["{major}.{minor}.{patch}"]
5+
search = "{current_version}"
6+
replace = "{new_version}"
7+
regex = false
8+
ignore_missing_version = false
9+
ignore_missing_files = false
10+
tag = true
11+
sign_tags = false
12+
tag_name = "v{new_version}"
13+
tag_message = "Bump version: {current_version} → {new_version}"
14+
allow_dirty = false
15+
commit = true
16+
message = "Bump version: {current_version} → {new_version}"
17+
commit_args = ""
18+
19+
[[tool.bumpversion.files]]
20+
filename = "pyproject.toml"
21+
search = "version = \"{current_version}\""
22+
replace = "version = \"{new_version}\""
23+
24+
[[tool.bumpversion.files]]
25+
filename = "src/tmo_api/_version.py"
26+
search = "__version__ = \"{current_version}\""
27+
replace = "__version__ = \"{new_version}\""
28+
29+
[[tool.bumpversion.files]]
30+
filename = "docs/changelog.md"
31+
search = "## [Unreleased]"
32+
replace = "## [Unreleased]\n\n## [{new_version}] - {now:%Y-%m-%d}"
33+
34+
[[tool.bumpversion.files]]
35+
filename = "docs/changelog.md"
36+
search = "[{current_version}]: https://github.com/inntran/tmo-api-python/releases/tag/v{current_version}"
37+
replace = "[{new_version}]: https://github.com/inntran/tmo-api-python/releases/tag/v{new_version}\n[{current_version}]: https://github.com/inntran/tmo-api-python/releases/tag/v{current_version}"

‎.github/workflows/publish.yml‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -22,16 +22,15 @@ jobs:
2222
with:
2323
python-version: "3.x"
2424

25-
- name: Install uv
26-
uses: astral-sh/setup-uv@v7
27-
with:
28-
enable-cache: auto
29-
python-version: "3.x"
25+
- name: Install build tools
26+
run: |
27+
python -m pip install --upgrade pip
28+
pip install build
3029
3130
- name: Build distributions
3231
run: |
3332
rm -rf dist
34-
uv build
33+
python -m build
3534
3635
- name: Publish to TestPyPI
3736
if: github.ref == 'refs/heads/staging'

‎RELEASING.md‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
# Release Process
2+
3+
This document describes how to release a new version of tmo-api.
4+
5+
## Tools
6+
7+
- **bump-my-version**: Manages version numbers and git tags
8+
- **git-cliff**: Generates changelog entries from git commits
9+
10+
## Quick Release Steps
11+
12+
### 1. Generate Changelog Entries
13+
14+
Use git-cliff to generate changelog entries from recent commits:
15+
16+
```bash
17+
# See changes since last tag
18+
git-cliff --unreleased
19+
20+
# See changes from specific commit range
21+
git-cliff HEAD~10..HEAD
22+
23+
# See changes since a specific tag
24+
git-cliff v0.0.1..HEAD
25+
26+
# Copy to clipboard (macOS)
27+
git-cliff --unreleased | pbcopy
28+
29+
# Copy to clipboard (Linux with xclip)
30+
git-cliff --unreleased | xclip -selection clipboard
31+
```
32+
33+
### 2. Update Changelog
34+
35+
Edit `docs/changelog.md` and add the generated entries under the `[Unreleased]` section:
36+
37+
```markdown
38+
## [Unreleased]
39+
40+
### Added
41+
- New feature X
42+
- New feature Y
43+
44+
### Fixed
45+
- Bug fix Z
46+
47+
### Changed
48+
- Updated something
49+
50+
## [0.0.1] - 2024-11-06
51+
...
52+
```
53+
54+
Commit your changelog updates:
55+
56+
```bash
57+
git add docs/changelog.md
58+
git commit -m "docs: Update changelog for upcoming release"
59+
```
60+
61+
### 3. Bump Version
62+
63+
Use bump-my-version to update version numbers and create git tags:
64+
65+
```bash
66+
# Bump patch version (0.0.1 → 0.0.2)
67+
bump-my-version bump patch
68+
69+
# Bump minor version (0.0.1 → 0.1.0)
70+
bump-my-version bump minor
71+
72+
# Bump major version (0.0.1 → 1.0.0)
73+
bump-my-version bump major
74+
75+
# Dry run to see what would change (requires clean working directory or --allow-dirty)
76+
bump-my-version bump --dry-run --allow-dirty patch
77+
```
78+
79+
This will automatically:
80+
- Update version in `pyproject.toml`
81+
- Update version in `src/tmo_api/_version.py`
82+
- Convert `[Unreleased]` to `[X.Y.Z] - YYYY-MM-DD` in `docs/changelog.md`
83+
- Add release link at the bottom of changelog
84+
- Create a git commit with message: `Bump version: X.Y.Z → X.Y.Z`
85+
- Create a git tag: `vX.Y.Z`
86+
87+
### 4. Push to GitHub
88+
89+
```bash
90+
# Push commits and tags
91+
git push && git push --tags
92+
```
93+
94+
### 5. Create GitHub Release
95+
96+
The GitHub Actions workflow will automatically create a release and publish to PyPI when you push the tag.
97+
98+
Alternatively, manually create a release on GitHub:
99+
1. Go to https://github.com/inntran/tmo-api-python/releases/new
100+
2. Select the tag you just created
101+
3. Copy the changelog section for this version as the release notes
102+
4. Publish the release
103+
104+
## Useful Commands
105+
106+
### Check Current Version
107+
108+
```bash
109+
bump-my-version show current_version
110+
```
111+
112+
### Show What Versions Would Be
113+
114+
```bash
115+
bump-my-version show-bump
116+
```
117+
118+
### View Recent Commits
119+
120+
```bash
121+
# Simple list
122+
git log --oneline -10
123+
124+
# With dates
125+
git log --pretty=format:"%h - %s (%ar)" -10
126+
127+
# Since last tag
128+
git log $(git describe --tags --abbrev=0)..HEAD --oneline
129+
```
130+
131+
### Customize git-cliff Output
132+
133+
Edit `cliff.toml` to customize:
134+
- Commit categorization rules
135+
- Output format
136+
- Which commits to include/exclude
137+
- GitHub issue linking
138+
139+
## Commit Message Guidelines
140+
141+
For better changelog generation, follow these conventions:
142+
143+
- **Added**: `Add`, `New`, `Implement`, `feat:`
144+
- **Fixed**: `Fix`, `Bug`, `Potential fix`
145+
- **Changed**: `Update`, `Increase`, `Set`
146+
- **Documentation**: `Doc`, `docs:`
147+
- **Security**: Include "security" in the message
148+
149+
Examples:
150+
```
151+
Add support for multiple authentication methods
152+
Fix rate limiting issue in API client
153+
Update dependencies to latest versions
154+
docs: Improve API documentation
155+
```
156+
157+
## Configuration Files
158+
159+
- `.bumpversion.toml` - bump-my-version configuration
160+
- `cliff.toml` - git-cliff configuration
161+
- `docs/changelog.md` - Changelog file
162+
163+
## Troubleshooting
164+
165+
### Git working directory is not clean
166+
167+
If bump-my-version complains about a dirty working directory:
168+
```bash
169+
# Check what's uncommitted
170+
git status
171+
172+
# Either commit your changes, or use --allow-dirty (not recommended for releases)
173+
bump-my-version bump --allow-dirty patch
174+
```
175+
176+
### No commits found
177+
178+
If git-cliff shows no commits, you might need to specify a range:
179+
```bash
180+
# All commits
181+
git-cliff
182+
183+
# Since beginning
184+
git-cliff --all
185+
```

‎cliff.toml‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
[changelog]
2+
# changelog header
3+
header = """
4+
# Changelog\n
5+
All notable changes to this project will be documented in this file.\n
6+
"""
7+
# template for the changelog body
8+
body = """
9+
{% if version %}\
10+
## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
11+
{% else %}\
12+
## [Unreleased]
13+
{% endif %}\
14+
{% for group, commits in commits | group_by(attribute="group") %}
15+
### {{ group | upper_first }}
16+
{% for commit in commits %}
17+
- {{ commit.message | upper_first }}\
18+
{% endfor %}
19+
{% endfor %}\n
20+
"""
21+
# remove the leading and trailing whitespace from the template
22+
trim = true
23+
# changelog footer
24+
footer = """
25+
<!-- generated by git-cliff -->
26+
"""
27+
28+
[git]
29+
# parse the commits based on https://www.conventionalcommits.org
30+
conventional_commits = true
31+
# filter out the commits that are not conventional (keep all commits)
32+
filter_unconventional = false
33+
# process each line of a commit as an individual commit
34+
split_commits = false
35+
# regex for preprocessing the commit messages
36+
commit_preprocessors = [
37+
{ pattern = '\((\w+\s)?#([0-9]+)\)', replace = "([#${2}](https://github.com/inntran/tmo-api-python/issues/${2}))" },
38+
]
39+
# regex for parsing and grouping commits
40+
commit_parsers = [
41+
{ message = "^feat", group = "Added" },
42+
{ message = "^[Aa]dd", group = "Added" },
43+
{ message = "^[Nn]ew", group = "Added" },
44+
{ message = "^[Ii]mplement", group = "Added" },
45+
{ message = "^fix", group = "Fixed" },
46+
{ message = "^[Ff]ix", group = "Fixed" },
47+
{ message = "^[Bb]ug", group = "Fixed" },
48+
{ message = "^[Pp]otential fix", group = "Fixed" },
49+
{ message = "^doc", group = "Documentation" },
50+
{ message = "^[Dd]oc", group = "Documentation" },
51+
{ message = "^perf", group = "Performance" },
52+
{ message = "^refactor", group = "Refactored" },
53+
{ message = "^style", group = "Styling" },
54+
{ message = "^test", group = "Testing" },
55+
{ message = "^[Uu]pdate", group = "Changed" },
56+
{ message = "^[Ii]ncrease", group = "Changed" },
57+
{ message = "^[Ss]et", group = "Changed" },
58+
{ message = "^chore\\(release\\):", skip = true },
59+
{ message = "^chore\\(deps\\)", skip = true },
60+
{ message = "^chore\\(pr\\)", skip = true },
61+
{ message = "^chore\\(pull\\)", skip = true },
62+
{ message = "^chore|^ci", group = "Miscellaneous" },
63+
{ body = ".*security", group = "Security" },
64+
{ message = ".*security", group = "Security" },
65+
{ message = "^revert", group = "Reverted" },
66+
]
67+
# protect breaking changes from being skipped due to matching a skipping commit_parser
68+
protect_breaking_commits = false
69+
# filter out the commits that are not matched by commit parsers
70+
filter_commits = false
71+
# glob pattern for matching git tags
72+
tag_pattern = "v[0-9]*"
73+
# regex for skipping tags
74+
skip_tags = "v0.0.1-beta.1"
75+
# regex for ignoring tags
76+
ignore_tags = ""
77+
# sort the tags topologically
78+
topo_order = false
79+
# sort the commits inside sections by oldest/newest order
80+
sort_commits = "oldest"
81+
# limit the number of commits included in the changelog.
82+
# limit_commits = 42

‎docs/changelog.md‎

Lines changed: 34 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,43 @@
22

33
All notable changes to this project will be documented in this file.
44

5-
## [0.0.1] - 2024-11-06
5+
## [Unreleased]
6+
### Added
7+
8+
- Add VScode Python pytest settings
9+
10+
### Changed
11+
12+
- Set package-ecosystem to 'pip' in dependabot config
13+
- Updated changed names in tests.
14+
15+
### Documentation
16+
17+
- Docs workflow runs only when triggered by others.
618

19+
### Fixed
20+
21+
- Fix Codecov upload condition and correct file parameter in CI workflow
22+
- Fix mypy typing issue, add CLI config tests
23+
24+
## [0.0.1] - 2024-11-06
725
### Added
26+
827
- Initial release
928
- Support for Pools, Partners, Distributions, Certificates, and History resources
10-
- Pool data models with date parsing
11-
- Comprehensive test suite (92% coverage)
12-
- Type hints with mypy support
13-
- Multi-environment support (US, Canada, Australia)
29+
30+
- Add GitHub Actions workflow for automated testing
31+
32+
- Update pyproject.toml:
33+
- Add requests dependency
34+
- Add dev dependencies (pytest, black, flake8, isort, mypy)
35+
- Configure tool settings for linting and testing
36+
37+
### Documentation
38+
- Getting Started: Installation, Quick Start, Authentication
39+
- User Guide: Client, Pools, Partners, Distributions, Certificates, History
40+
- API Reference: Client, Models, Resources, Exceptions
41+
- Contributing: Development Setup, Testing, Code Style
42+
- Changelog
1443

1544
[0.0.1]: https://github.com/inntran/tmo-api-python/releases/tag/v0.0.1

‎pyproject.toml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,8 @@ Repository = "https://github.com/inntran/tmo-api-python"
3636
Issues = "https://github.com/inntran/tmo-api-python/issues"
3737

3838
[project.scripts]
39+
tmolo = "tmo_api.cli.tmolo:main"
40+
tmols = "tmo_api.cli.tmols:main"
3941
tmopo = "tmo_api.cli.tmopo:main"
4042
tmoapi = "tmo_api.cli.tmoapi:main"
4143

@@ -52,6 +54,7 @@ dev = [
5254
"types-openpyxl>=3.1.0",
5355
"types-docutils>=0.20.0",
5456
"types-Pygments>=2.17.0",
57+
"bump-my-version>=0.28.1",
5558
]
5659
docs = [
5760
"mkdocs>=1.6.0",

0 commit comments

Comments
 (0)