Skip to content

Commit 324baf4

Browse files
thedumbtechguythedumbtechguy
committed
docs: setup contribution guidelines using Conventional Commits
Add comprehensive release automation workflow: - Configure git-cliff for automated changelog generation - Add rake tasks for version bumping and release management - Setup GitHub Actions for automated RubyGems publishing - Document conventional commit format and release process
1 parent 754a4f5 commit 324baf4

File tree

6 files changed

+577
-0
lines changed

6 files changed

+577
-0
lines changed

‎.cliff.toml‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# git-cliff configuration file
2+
# https://git-cliff.org/docs/configuration
3+
4+
[changelog]
5+
# changelog header
6+
header = """
7+
# Changelog\n
8+
All notable changes to this project will be documented in this file.\n
9+
"""
10+
# template for the changelog body
11+
body = """
12+
{% if version %}\
13+
## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
14+
{% else %}\
15+
## [Unreleased]
16+
{% endif %}\
17+
{% for group, commits in commits | group_by(attribute="group") %}
18+
### {{ group | upper_first }}
19+
{% for commit in commits %}
20+
- {% if commit.breaking %}[**breaking**] {% endif %}{{ commit.message | upper_first }}\
21+
{% endfor %}
22+
{% endfor %}\n
23+
"""
24+
# remove the leading and trailing whitespace from the template
25+
trim = true
26+
# changelog footer
27+
footer = """
28+
<!-- generated by git-cliff -->
29+
"""
30+
31+
[git]
32+
# parse the commits based on https://www.conventionalcommits.org
33+
conventional_commits = true
34+
# filter out the commits that are not conventional
35+
filter_unconventional = true
36+
# process each line of a commit as an individual commit
37+
split_commits = false
38+
# regex for preprocessing the commit messages
39+
commit_preprocessors = [
40+
{ pattern = '\((\w+\s)?#([0-9]+)\)', replace = "([#${2}](https://github.com/radioactive-labs/plutonium-core/issues/${2}))" },
41+
]
42+
# regex for parsing and grouping commits
43+
commit_parsers = [
44+
{ message = "^feat", group = "Features" },
45+
{ message = "^fix", group = "Bug Fixes" },
46+
{ message = "^doc", group = "Documentation" },
47+
{ message = "^perf", group = "Performance" },
48+
{ message = "^refactor", group = "Refactoring" },
49+
{ message = "^style", group = "Styling" },
50+
{ message = "^test", group = "Testing" },
51+
{ message = "^chore\\(release\\): prepare for", skip = true },
52+
{ message = "^chore", group = "Miscellaneous Tasks" },
53+
{ body = ".*security", group = "Security" },
54+
]
55+
# protect breaking changes from being skipped due to matching a skipping commit_parser
56+
protect_breaking_commits = false
57+
# filter out the commits that are not matched by commit parsers
58+
filter_commits = false
59+
# glob pattern for matching git tags
60+
tag_pattern = "v[0-9]*"
61+
# regex for skipping tags
62+
skip_tags = "v0.1.0-beta.1"
63+
# regex for ignoring tags
64+
ignore_tags = ""
65+
# sort the tags topologically
66+
topo_order = false
67+
# sort the commits inside sections by oldest/newest order
68+
sort_commits = "oldest"

‎.github/RELEASE.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
# Release Workflow Quick Reference
2+
3+
## Prerequisites
4+
5+
```bash
6+
# Install git-cliff (one-time setup)
7+
brew install git-cliff # macOS
8+
# or
9+
cargo install git-cliff # via Rust/Cargo
10+
```
11+
12+
## Quick Release
13+
14+
```bash
15+
# One-command release
16+
rake release:full[0.27.0]
17+
```
18+
19+
This will:
20+
1. ✓ Check for uncommitted changes
21+
2. ✓ Update version in `lib/plutonium/version.rb`
22+
3. ✓ Generate/update CHANGELOG.md
23+
4. ✓ Create commit: `chore(release): prepare for v0.27.0`
24+
5. ✓ Create git tag: `v0.27.0`
25+
6. ✓ Push to GitHub
26+
7. ✓ Trigger GitHub Action to publish to RubyGems
27+
28+
## Step-by-Step Release
29+
30+
### 1. Check Next Version
31+
32+
```bash
33+
rake release:next_version
34+
```
35+
36+
This analyzes commits since last tag and suggests version bump.
37+
38+
### 2. Prepare Release
39+
40+
```bash
41+
rake release:prepare[0.27.0]
42+
```
43+
44+
Updates version file and generates changelog.
45+
46+
### 3. Review Changes
47+
48+
```bash
49+
git diff
50+
cat CHANGELOG.md
51+
```
52+
53+
### 4. Commit & Tag
54+
55+
```bash
56+
git add -A
57+
git commit -m "chore(release): prepare for v0.27.0"
58+
git tag v0.27.0
59+
```
60+
61+
### 5. Push
62+
63+
```bash
64+
git push origin main --tags
65+
```
66+
67+
### 6. Publish (Automated)
68+
69+
GitHub Actions will automatically:
70+
- Build the gem
71+
- Publish to RubyGems
72+
- Create GitHub release with notes
73+
74+
## Manual Changelog Generation
75+
76+
```bash
77+
# Generate changelog for specific tag
78+
git-cliff --tag v0.27.0 -o CHANGELOG.md
79+
80+
# Generate changelog between tags
81+
git-cliff v0.26.0..v0.27.0
82+
83+
# Preview unreleased changes
84+
git-cliff --unreleased
85+
```
86+
87+
## Conventional Commit Cheat Sheet
88+
89+
```bash
90+
# New feature (minor bump: 0.26.x → 0.27.0)
91+
git commit -m "feat: add new feature"
92+
93+
# Bug fix (patch bump: 0.26.11 → 0.26.12)
94+
git commit -m "fix: resolve bug"
95+
96+
# Breaking change (major bump: 0.x.x → 1.0.0)
97+
git commit -m "feat!: breaking change"
98+
99+
# With scope
100+
git commit -m "feat(ui): add component"
101+
git commit -m "fix(forms): fix validation"
102+
103+
# Documentation (no version bump)
104+
git commit -m "docs: update guide"
105+
106+
# Chore (no version bump)
107+
git commit -m "chore: update dependencies"
108+
```
109+
110+
## Troubleshooting
111+
112+
### "git-cliff: command not found"
113+
114+
Install git-cliff:
115+
```bash
116+
brew install git-cliff
117+
```
118+
119+
### "Gem push failed"
120+
121+
Ensure RubyGems API key is configured:
122+
```bash
123+
gem signin
124+
```
125+
126+
Or add to `~/.gem/credentials`:
127+
```yaml
128+
---
129+
:rubygems_api_key: YOUR_API_KEY
130+
```
131+
132+
### GitHub Action not running
133+
134+
1. Check that tag was pushed: `git push origin main --tags`
135+
2. Verify RUBYGEMS_API_KEY secret is set in GitHub repo settings
136+
3. Check Actions tab for workflow runs
137+
138+
## Version Bump Decision Tree
139+
140+
```
141+
Has BREAKING CHANGE or `!`?
142+
├─ Yes → MAJOR (1.0.0, 2.0.0, etc)
143+
└─ No
144+
└─ Has `feat:`?
145+
├─ Yes → MINOR (0.1.0, 0.2.0, etc)
146+
└─ No
147+
└─ Has `fix:`?
148+
├─ Yes → PATCH (0.0.1, 0.0.2, etc)
149+
└─ No → No version bump
150+
```
151+
152+
## Emergency Patch
153+
154+
For urgent fixes without full release prep:
155+
156+
```bash
157+
# 1. Make fix with conventional commit
158+
git commit -m "fix: critical security issue"
159+
160+
# 2. Quick release
161+
rake release:full[0.26.12]
162+
```

‎.github/workflows/release.yml‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
name: Release
2+
3+
on:
4+
push:
5+
tags:
6+
- 'v*'
7+
8+
permissions:
9+
contents: write
10+
11+
jobs:
12+
release:
13+
runs-on: ubuntu-latest
14+
15+
steps:
16+
- uses: actions/checkout@v4
17+
with:
18+
fetch-depth: 0
19+
20+
- name: Set up Ruby
21+
uses: ruby/setup-ruby@v1
22+
with:
23+
ruby-version: '3.2'
24+
bundler-cache: true
25+
26+
- name: Extract version from tag
27+
id: version
28+
run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
29+
30+
- name: Build gem
31+
run: gem build plutonium.gemspec
32+
33+
- name: Publish to RubyGems
34+
env:
35+
GEM_HOST_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}
36+
run: |
37+
mkdir -p ~/.gem
38+
cat << EOF > ~/.gem/credentials
39+
---
40+
:rubygems_api_key: ${GEM_HOST_API_KEY}
41+
EOF
42+
chmod 0600 ~/.gem/credentials
43+
gem push plutonium-${{ steps.version.outputs.VERSION }}.gem
44+
45+
- name: Install git-cliff
46+
uses: taiki-e/install-action@v2
47+
with:
48+
tool: git-cliff
49+
50+
- name: Generate release notes
51+
run: |
52+
git-cliff --config .cliff.toml --tag ${{ github.ref_name }} --strip all > RELEASE_NOTES.md
53+
54+
- name: Create GitHub Release
55+
uses: softprops/action-gh-release@v1
56+
with:
57+
body_path: RELEASE_NOTES.md
58+
files: |
59+
plutonium-${{ steps.version.outputs.VERSION }}.gem
60+
env:
61+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

0 commit comments

Comments
 (0)