Skip to content

Commit 0109729

Browse files
pritkcpritkc
committed
MOLE v1.1.0
- Add comprehensive release documentation (RELEASING.md) - Set up automated release notes generation workflow - Update CITATION.cff with version and release date - Prepare for DOI-bearing release on Zenodo This release includes substantial improvements since v1.0: - New documentation system with Sphinx/ReadTheDocs - Automated test suites for C++ and MATLAB/Octave - Directory restructuring (matlab -> matlab_octave) - Security vulnerability fixes - Enhanced CI/CD workflows - Community contributions and bug fixes 110 commits with contributions from multiple developers.
1 parent 732d57a commit 0109729

File tree

3 files changed

+270
-0
lines changed

3 files changed

+270
-0
lines changed

‎.github/workflows/release-notes.yml‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
name: Generate Release Notes
2+
3+
on:
4+
push:
5+
tags:
6+
- 'v*'
7+
8+
permissions:
9+
contents: write
10+
pull-requests: read
11+
12+
jobs:
13+
release-notes:
14+
runs-on: ubuntu-latest
15+
steps:
16+
- name: Checkout code
17+
uses: actions/checkout@v4
18+
with:
19+
fetch-depth: 0
20+
21+
- name: Generate Release Notes
22+
id: release_notes
23+
run: |
24+
# Get the previous tag
25+
PREVIOUS_TAG=$(git tag --sort=-version:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+' | sed -n '2p')
26+
CURRENT_TAG=${GITHUB_REF#refs/tags/}
27+
28+
echo "Generating release notes from ${PREVIOUS_TAG} to ${CURRENT_TAG}"
29+
30+
# Create release notes
31+
echo "# Release Notes for ${CURRENT_TAG}" > release_notes.md
32+
echo "" >> release_notes.md
33+
34+
if [ -n "$PREVIOUS_TAG" ]; then
35+
echo "## Changes since ${PREVIOUS_TAG}" >> release_notes.md
36+
echo "" >> release_notes.md
37+
38+
# Get commits since last tag
39+
git log --first-parent --pretty=format:"* %s" ${PREVIOUS_TAG}..HEAD >> release_notes.md
40+
echo "" >> release_notes.md
41+
echo "" >> release_notes.md
42+
43+
# Get merged PRs
44+
echo "## Pull Requests Merged" >> release_notes.md
45+
echo "" >> release_notes.md
46+
git log --first-parent --grep="Merge pull request" --pretty=format:"* %s" ${PREVIOUS_TAG}..HEAD >> release_notes.md
47+
echo "" >> release_notes.md
48+
echo "" >> release_notes.md
49+
50+
# Get contributors
51+
echo "## Contributors" >> release_notes.md
52+
echo "" >> release_notes.md
53+
git log --first-parent --pretty=format:"%an" ${PREVIOUS_TAG}..HEAD | sort -u | sed 's/^/* /' >> release_notes.md
54+
else
55+
echo "## Initial Release" >> release_notes.md
56+
echo "" >> release_notes.md
57+
echo "This is the first tagged release of MOLE." >> release_notes.md
58+
fi
59+
60+
# Set output for use in next step
61+
echo "release_notes_file=release_notes.md" >> $GITHUB_OUTPUT
62+
63+
- name: Create Release
64+
uses: softprops/action-gh-release@v2
65+
with:
66+
tag_name: ${{ github.ref_name }}
67+
name: MOLE ${{ github.ref_name }}
68+
body_path: release_notes.md
69+
draft: false
70+
prerelease: false
71+
generate_release_notes: true
72+
env:
73+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
74+
75+
- name: Upload Release Notes as Artifact
76+
uses: actions/upload-artifact@v4
77+
with:
78+
name: release-notes-${{ github.ref_name }}
79+
path: release_notes.md

‎CITATION.cff‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@ contact:
1212
given-names: Johnny
1313
orcid: "https://orcid.org/0000-0002-2638-9216"
1414
doi: 10.5281/zenodo.12752946
15+
version: "1.1.0"
16+
date-released: "2025-08-13"
1517
message: If you use this software, please cite our article in the
1618
Journal of Open Source Software.
1719
preferred-citation:

‎RELEASING.md‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
# Release Procedures
2+
3+
*These notes are meant for a maintainer to create official releases of MOLE.*
4+
5+
In preparing a release, create a branch to hold pre-release commits.
6+
We ideally want all release mechanics to be in one commit, which will then be tagged.
7+
8+
## Core Library Release
9+
10+
Some minor bookkeeping updates are needed when releasing a new version of MOLE.
11+
12+
The version number must be updated in:
13+
14+
* `CITATION.cff` (update the `doi` field and `date-published` if needed)
15+
* `README.md` (if version-specific badges or information exist)
16+
17+
Additionally, the release notes should be generated and reviewed.
18+
Use `git log --first-parent v1.0..` to get a sense of the pull requests that have been merged since the last release and thus might warrant emphasizing in the release notes.
19+
20+
While doing this, gather a couple sentences for key features to highlight on [GitHub releases](https://github.com/csrc-sdsu/mole/releases).
21+
22+
### Quality control and good citizenry
23+
24+
1. **Testing**: Ensure all tests pass on supported platforms:
25+
- Run `make run_tests` for C++ tests
26+
- Run `make run_matlab_octave_tests` for MATLAB/Octave tests
27+
- Verify CI passes on all platforms (Ubuntu, macOS)
28+
29+
2. **Documentation**: Ensure documentation builds successfully:
30+
- Check that the documentation workflow passes
31+
- Verify examples work correctly
32+
- Review any new documentation for accuracy
33+
34+
3. **Dependencies**: Check that all dependencies are properly specified and up-to-date:
35+
- Verify CMake builds work on supported platforms
36+
- Check that installation instructions are current
37+
38+
### Tagging and releasing on GitHub
39+
40+
1. **Prepare the release commit**:
41+
```bash
42+
git commit -am "MOLE v1.1.0"
43+
```
44+
More frequently, this is amending the commit message on an in-progress commit, after rebasing if applicable on latest `main`.
45+
46+
2. **Push and review**:
47+
```bash
48+
git push
49+
```
50+
This updates the PR holding release; opportunity for others to review.
51+
52+
3. **Merge to main**:
53+
```bash
54+
git switch main && git merge --ff-only HEAD@{1}
55+
```
56+
Fast-forward merge into `main`.
57+
58+
4. **Tag the release**:
59+
```bash
60+
git tag -a v1.1.0 -m "MOLE v1.1.0"
61+
```
62+
63+
5. **Push tag**:
64+
```bash
65+
git push origin main v1.1.0
66+
```
67+
68+
6. **Create GitHub Release**:
69+
- Go to [GitHub releases page](https://github.com/csrc-sdsu/mole/releases)
70+
- Click "Draft a new release"
71+
- Select the newly created tag
72+
- Use the tag name as the release title
73+
- Copy release notes from the automated generation (see below)
74+
- Add a few sentences highlighting key features
75+
- Publish the release
76+
77+
### Archive Documentation on Zenodo
78+
79+
For DOI-bearing releases:
80+
81+
1. **Generate documentation PDF**: The documentation workflow automatically generates a PDF version
82+
2. **Update Zenodo record**:
83+
- Visit the [MOLE Zenodo record](https://zenodo.org/record/12752946) (update URL as needed)
84+
- Click "New version"
85+
- Upload the generated PDF documentation
86+
- Update author information if applicable
87+
- Publish the new version
88+
89+
3. **Update repository with new DOI**:
90+
- Update `CITATION.cff` with the new DOI
91+
- Update `README.md` with the new DOI if referenced
92+
- Create a follow-up PR with these updates
93+
94+
## Automated Release Notes
95+
96+
MOLE uses GitHub Actions to automatically generate release notes when a new tag is pushed.
97+
98+
### How it works
99+
100+
The release notes generation workflow:
101+
1. Triggers automatically when a tag matching `v*` is pushed
102+
2. Analyzes commits since the last release
103+
3. Generates release notes based on commit messages and PR titles
104+
4. Creates or updates the GitHub release with the generated notes
105+
106+
### Manual review and adjustment
107+
108+
While automation helps, always review the generated release notes:
109+
1. Check for accuracy and completeness
110+
2. Add context for major changes
111+
3. Highlight breaking changes or important updates
112+
4. Ensure proper formatting and readability
113+
114+
If manual adjustments are needed, you can use:
115+
```bash
116+
git log --first-parent v1.0..
117+
```
118+
to review changes since the last release.
119+
120+
## Version Numbering
121+
122+
MOLE follows [semantic versioning](https://semver.org/):
123+
124+
- **MAJOR** version (X.y.z): Incompatible API changes
125+
- **MINOR** version (x.Y.z): New functionality in a backwards compatible manner
126+
- **PATCH** version (x.y.Z): Backwards compatible bug fixes
127+
128+
Examples:
129+
- `v1.0.0` → `v1.1.0`: New features added (documentation system, test suites)
130+
- `v1.1.0` → `v1.1.1`: Bug fixes only
131+
- `v1.1.0` → `v2.0.0`: Breaking changes to API
132+
133+
## Release Checklist
134+
135+
Before creating a release:
136+
137+
- [ ] All tests pass on supported platforms
138+
- [ ] Documentation builds successfully
139+
- [ ] Version numbers updated in relevant files
140+
- [ ] CHANGELOG or release notes prepared
141+
- [ ] Dependencies verified and up-to-date
142+
- [ ] Installation instructions tested
143+
- [ ] Examples work correctly
144+
- [ ] CI/CD workflows pass
145+
146+
After creating a release:
147+
148+
- [ ] GitHub release created with proper notes
149+
- [ ] Zenodo record updated (if applicable)
150+
- [ ] DOI updated in repository files
151+
- [ ] Community notified (if appropriate)
152+
- [ ] Package managers updated (if applicable)
153+
154+
## Troubleshooting
155+
156+
### Common Issues
157+
158+
1. **Tag already exists**: If you need to retag, delete the tag locally and remotely:
159+
```bash
160+
git tag -d v1.1.0
161+
git push origin :refs/tags/v1.1.0
162+
```
163+
164+
2. **CI failures**: Ensure all workflows pass before tagging. Check:
165+
- Build and test workflows
166+
- Documentation generation
167+
- Linting and code quality
168+
169+
3. **Documentation issues**: If documentation fails to build:
170+
- Check for missing dependencies
171+
- Verify all referenced files exist
172+
- Review recent changes to documentation source
173+
174+
### Getting Help
175+
176+
If you encounter issues during the release process:
177+
1. Check existing GitHub issues for similar problems
178+
2. Review the CI/CD workflow logs for detailed error messages
179+
3. Consult the project maintainers
180+
4. Refer to the [contributing guidelines](CONTRIBUTING.md)
181+
182+
## Post-Release Tasks
183+
184+
After a successful release:
185+
186+
1. **Update development version**: Consider updating version numbers to indicate development status
187+
2. **Monitor for issues**: Watch for bug reports related to the new release
188+
3. **Update documentation**: Ensure all documentation reflects the latest release
189+
4. **Community engagement**: Announce the release through appropriate channels

0 commit comments

Comments
 (0)