Skip to content

Commit 2541a03

Browse files
yibeichanyibeichan
committed
feat: add simple release workflow and documentation
- Add manual release workflow using GitHub Actions - Create CHANGELOG.md to track version history - Add CONTRIBUTING.md with development and release guidelines - Use built-in GITHUB_TOKEN for security - Support semantic versioning with version validation - Automatically update version in pyproject.toml and cookiecutter.json - Generate release notes automatically This replaces the complex auto-based workflow from PR #7 with a simpler, more maintainable approach suitable for cookiecutter templates.
1 parent be4a935 commit 2541a03

File tree

3 files changed

+349
-0
lines changed

3 files changed

+349
-0
lines changed

‎.github/workflows/release.yml‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
name: Release
2+
3+
on:
4+
workflow_dispatch:
5+
inputs:
6+
version:
7+
description: 'Version to release (e.g., 1.0.1)'
8+
required: true
9+
type: string
10+
release_type:
11+
description: 'Release type'
12+
required: true
13+
type: choice
14+
options:
15+
- patch
16+
- minor
17+
- major
18+
19+
permissions:
20+
contents: write
21+
22+
jobs:
23+
release:
24+
runs-on: ubuntu-latest
25+
26+
steps:
27+
- uses: actions/checkout@v4
28+
with:
29+
fetch-depth: 0
30+
token: ${{ secrets.GITHUB_TOKEN }}
31+
32+
- name: Set up Python
33+
uses: actions/setup-python@v5
34+
with:
35+
python-version: '3.11'
36+
37+
- name: Install dependencies
38+
run: |
39+
python -m pip install --upgrade pip
40+
pip install toml
41+
42+
- name: Validate version format
43+
run: |
44+
if ! echo "${{ inputs.version }}" | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$'; then
45+
echo "Error: Version must be in format X.Y.Z"
46+
exit 1
47+
fi
48+
49+
- name: Check if tag already exists
50+
run: |
51+
if git rev-parse "v${{ inputs.version }}" >/dev/null 2>&1; then
52+
echo "Error: Tag v${{ inputs.version }} already exists"
53+
exit 1
54+
fi
55+
56+
- name: Wait for tests to complete
57+
uses: lewagon/[email protected]
58+
with:
59+
ref: ${{ github.sha }}
60+
check-name: 'Test template generation'
61+
repo-token: ${{ secrets.GITHUB_TOKEN }}
62+
wait-interval: 10
63+
64+
- name: Update version in pyproject.toml
65+
run: |
66+
python -c "
67+
import toml
68+
import sys
69+
70+
# Read the current pyproject.toml
71+
with open('pyproject.toml', 'r') as f:
72+
data = toml.load(f)
73+
74+
# Update the version
75+
data['project']['version'] = '${{ inputs.version }}'
76+
77+
# Write back
78+
with open('pyproject.toml', 'w') as f:
79+
toml.dump(data, f)
80+
"
81+
82+
- name: Update version in cookiecutter.json
83+
run: |
84+
python -c "
85+
import json
86+
87+
# Read cookiecutter.json
88+
with open('cookiecutter.json', 'r') as f:
89+
data = json.load(f)
90+
91+
# Add version field if it doesn't exist
92+
data['_template_version'] = '${{ inputs.version }}'
93+
94+
# Write back with proper formatting
95+
with open('cookiecutter.json', 'w') as f:
96+
json.dump(data, f, indent=4)
97+
f.write('\n')
98+
"
99+
100+
- name: Commit version updates
101+
run: |
102+
git config user.name "github-actions[bot]"
103+
git config user.email "github-actions[bot]@users.noreply.github.com"
104+
git add pyproject.toml cookiecutter.json
105+
git commit -m "chore: bump version to ${{ inputs.version }}"
106+
git push origin main
107+
108+
- name: Create and push tag
109+
run: |
110+
git tag -a "v${{ inputs.version }}" -m "Release v${{ inputs.version }}"
111+
git push origin "v${{ inputs.version }}"
112+
113+
- name: Generate release notes
114+
id: release_notes
115+
run: |
116+
# Get the previous tag
117+
PREV_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")
118+
119+
if [ -z "$PREV_TAG" ]; then
120+
echo "No previous tag found, this is the first release"
121+
COMPARE_FROM=$(git rev-list --max-parents=0 HEAD)
122+
else
123+
COMPARE_FROM=$PREV_TAG
124+
fi
125+
126+
# Generate commit list
127+
echo "commits<<EOF" >> $GITHUB_OUTPUT
128+
git log --pretty=format:"- %s (%h)" $COMPARE_FROM..HEAD >> $GITHUB_OUTPUT
129+
echo "" >> $GITHUB_OUTPUT
130+
echo "EOF" >> $GITHUB_OUTPUT
131+
132+
- name: Create Release
133+
uses: softprops/action-gh-release@v2
134+
with:
135+
tag_name: v${{ inputs.version }}
136+
name: Release v${{ inputs.version }}
137+
draft: false
138+
prerelease: false
139+
generate_release_notes: true
140+
body: |
141+
## 🎉 Release v${{ inputs.version }}
142+
143+
**Release type**: ${{ inputs.release_type }}
144+
145+
### For Users of This Template
146+
147+
To update your existing protocol generated from this template:
148+
```bash
149+
cruft update
150+
```
151+
152+
Or to create a new protocol:
153+
```bash
154+
cookiecutter gh:ReproNim/reproschema-protocol-cookiecutter
155+
```
156+
157+
### What's Changed
158+
159+
Auto-generated release notes are below.

‎CHANGELOG.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [Unreleased]
9+
10+
### Added
11+
- GitHub Pages deployment workflow for generated protocols
12+
- Comprehensive testing infrastructure with CI/CD
13+
- Improved error handling in post-generation hooks
14+
- Support for deploying specific versions/commits to GitHub Pages
15+
16+
### Changed
17+
- Updated all schemas to use stable ReproSchema version 1.0.0
18+
- Standardized schema filenames to lowercase convention
19+
- Fixed context paths from `/contexts/generic` to `/contexts/reproschema`
20+
21+
### Fixed
22+
- Schema version inconsistencies
23+
- Hardcoded activity references in protocol template
24+
- Path mismatches in generated schemas
25+
26+
## [1.0.0] - 2024-06-12
27+
28+
### Added
29+
- Initial release of reproschema-protocol-cookiecutter
30+
- Support for generating ReproSchema protocols
31+
- Customizable number of activities (1-5)
32+
- Pre-configured activity types:
33+
- Basic activities with various input types
34+
- Voice recording activities
35+
- Selection activities
36+
- Integration with reproschema-ui
37+
- Cruft support for template updates
38+
- Basic documentation and examples
39+
40+
[Unreleased]: https://github.com/ReproNim/reproschema-protocol-cookiecutter/compare/v1.0.0...HEAD
41+
[1.0.0]: https://github.com/ReproNim/reproschema-protocol-cookiecutter/releases/tag/v1.0.0

‎CONTRIBUTING.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
# Contributing to reproschema-protocol-cookiecutter
2+
3+
Thank you for your interest in contributing to the ReproSchema Protocol Cookiecutter! This document provides guidelines and instructions for contributing.
4+
5+
## Getting Started
6+
7+
1. Fork the repository
8+
2. Clone your fork: `git clone https://github.com/YOUR-USERNAME/reproschema-protocol-cookiecutter.git`
9+
3. Create a new branch: `git checkout -b feature/your-feature-name`
10+
4. Make your changes
11+
5. Test your changes (see Testing section)
12+
6. Commit your changes using conventional commits
13+
7. Push to your fork and submit a pull request
14+
15+
## Development Setup
16+
17+
### Prerequisites
18+
19+
- Python 3.8+
20+
- Node.js 20+ (for testing GitHub Pages deployment)
21+
- Git
22+
23+
### Installing Dependencies
24+
25+
```bash
26+
pip install -r requirements.txt
27+
```
28+
29+
### Pre-commit Hooks
30+
31+
We use pre-commit hooks to ensure code quality:
32+
33+
```bash
34+
pre-commit install
35+
```
36+
37+
## Testing
38+
39+
### Running Tests Locally
40+
41+
```bash
42+
# Test the cookiecutter template generation
43+
python test_cookiecutter.py
44+
45+
# Or use the micromamba environment
46+
./run_in_env.sh python test_cookiecutter.py
47+
```
48+
49+
### Testing Your Changes
50+
51+
1. Generate a test protocol:
52+
```bash
53+
cookiecutter . --no-input -o test-output
54+
```
55+
56+
2. Validate the generated schemas:
57+
```bash
58+
cd test-output/my-reproschema-protocol
59+
reproschema validate my_reproschema_protocol/my_reproschema_protocol_schema
60+
```
61+
62+
## Code Style
63+
64+
- Python code follows PEP 8
65+
- Use meaningful variable and function names
66+
- Add docstrings to functions
67+
- Keep functions focused and small
68+
69+
## Commit Messages
70+
71+
We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification:
72+
73+
- `feat:` New features
74+
- `fix:` Bug fixes
75+
- `docs:` Documentation changes
76+
- `chore:` Maintenance tasks
77+
- `test:` Test additions or modifications
78+
79+
Example:
80+
```
81+
feat: add support for custom activity types
82+
83+
- Allow users to define custom activity schemas
84+
- Update documentation with examples
85+
- Add tests for custom activities
86+
```
87+
88+
## Pull Request Process
89+
90+
1. Ensure all tests pass
91+
2. Update documentation if needed
92+
3. Update CHANGELOG.md with your changes under "Unreleased"
93+
4. Fill out the PR template completely
94+
5. Request review from maintainers
95+
96+
## Release Process
97+
98+
Releases are managed by maintainers using the GitHub Actions release workflow:
99+
100+
### Creating a Release
101+
102+
1. Go to Actions → Release workflow
103+
2. Click "Run workflow"
104+
3. Enter the new version (e.g., 1.0.1)
105+
4. Select release type (patch/minor/major)
106+
5. The workflow will:
107+
- Update version in pyproject.toml and cookiecutter.json
108+
- Create a git tag
109+
- Generate release notes
110+
- Create a GitHub release
111+
112+
### Version Guidelines
113+
114+
- **Major** (X.0.0): Breaking changes to template structure or output
115+
- **Minor** (1.X.0): New features, activities, or capabilities
116+
- **Patch** (1.0.X): Bug fixes, documentation updates
117+
118+
### Post-Release
119+
120+
After a release, update CHANGELOG.md:
121+
1. Move items from "Unreleased" to the new version section
122+
2. Add comparison link at the bottom
123+
124+
## Schema Updates
125+
126+
When updating ReproSchema versions or structures:
127+
128+
1. Use `update_schema_version.py` to update all schemas consistently
129+
2. Test that all schemas validate with the new version
130+
3. Update documentation to reflect changes
131+
132+
## Adding New Activities
133+
134+
To add a new activity type:
135+
136+
1. Create the activity folder in `{{cookiecutter.protocol_name}}/activities/`
137+
2. Add the activity schema and item schemas
138+
3. Update `hooks/pre_gen_project.py` to include the new activity option
139+
4. Add tests for the new activity
140+
5. Update documentation
141+
142+
## Questions?
143+
144+
Feel free to:
145+
- Open an issue for bugs or feature requests
146+
- Start a discussion for questions
147+
- Join the ReproNim community channels
148+
149+
Thank you for contributing!

0 commit comments

Comments
 (0)