Skip to content

Commit d4dc736

Browse files
mrvisschermrvisscher
committed
Workflow readme
1 parent 7c43c07 commit d4dc736

1 file changed

Lines changed: 192 additions & 0 deletions

File tree

‎.github/workflows/README.md‎

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
# GitHub Actions Workflows
2+
3+
This document describes the GitHub Actions workflows used in the Activity Browser project.
4+
5+
## Overview
6+
7+
The Activity Browser project uses five GitHub Actions workflows to automate testing, deployment, and project management tasks:
8+
9+
1. **Automated Testing** - Runs tests on every push and PR
10+
2. **Canary Installation** - Daily installation checks to catch dependency issues
11+
3. **Beta Deployment** - Publishes beta releases to PyPI and Anaconda
12+
4. **Stable Release** - Creates releases and publishes to Anaconda
13+
5. **Milestone Comments** - Automatically notifies users when issues are resolved in releases
14+
15+
---
16+
17+
## 1. Automated Testing (`testing.yaml`)
18+
19+
**Trigger:** Push or pull request to the `major` branch
20+
21+
**Purpose:** Ensures code quality by running the test suite across multiple operating systems and Python versions.
22+
23+
### Matrix Strategy
24+
- **Operating Systems:** Ubuntu (latest), Windows (latest), macOS 15, macOS (latest)
25+
- **Python Versions:** 3.10, 3.11, 3.12
26+
- **Total combinations:** 12 test runs per trigger
27+
28+
### Steps
29+
1. Checkout code
30+
2. Set up Python for the specified version
31+
3. Install Qt libraries (Linux only)
32+
4. Update pip, setuptools, and wheel
33+
5. Install package with testing dependencies: `pip install .[testing]`
34+
6. Run pytest with minimal output: `pytest -s --no-header --no-summary -q`
35+
36+
### Environment
37+
- Sets `QT_QPA_PLATFORM=offscreen` for headless GUI testing
38+
- Uses `fail-fast: false` to run all combinations even if some fail
39+
40+
---
41+
42+
## 2. Canary Installation (`install-canary.yaml`)
43+
44+
**Trigger:** Scheduled daily at 7:00 AM UTC (cron: `0 7 * * *`)
45+
46+
**Purpose:** Proactively detects dependency issues by performing fresh installations of Activity Browser from PyPI daily.
47+
48+
### Matrix Strategy
49+
- **Operating Systems:** Ubuntu (latest), Windows (latest), macOS 15, macOS (latest)
50+
- **Python Versions:** 3.10, 3.11, 3.12
51+
- **Timeout:** 12 minutes per job
52+
53+
### Steps
54+
1. Checkout code
55+
2. Set up Python
56+
3. Install activity-browser from PyPI (not from source)
57+
4. Generate environment info with `pip freeze`
58+
5. Upload frozen requirements as artifact for each OS/Python combination
59+
60+
### Notes
61+
- Uses `bash -e {0}` shell to exit on error
62+
- Helps catch breaking changes in dependencies before users encounter them
63+
- Artifacts show exact dependency versions that successfully installed
64+
65+
---
66+
67+
## 3. Beta Deployment (`python-package-deploy.yml`)
68+
69+
**Trigger:** Push to `beta` branch or any tag
70+
71+
**Purpose:** Publishes beta versions to PyPI (test and production) and Anaconda Cloud.
72+
73+
### Version Scheme
74+
- Beta version format: `3.0.0b<N>` where N is the commit count since commit `199b6c3`
75+
- Calculated dynamically: `git rev-list 199b6c3..HEAD --count`
76+
77+
### Steps
78+
1. Checkout with full git history (`fetch-depth: "0"`)
79+
2. Calculate and set version number
80+
3. Set up Python 3.11
81+
4. Install `build` package
82+
5. Build wheel and source distribution
83+
6. **PyPI Publishing:**
84+
- Publish to Test PyPI (with `skip-existing: true`)
85+
- Publish to production PyPI
86+
7. **Conda Publishing:**
87+
- Set up Conda environment from `.github/conda-envs/build.yml`
88+
- Build Conda package: `conda build -c conda-forge -c cmutel ./recipe/`
89+
- Upload to Anaconda Cloud using `CONDA_LCA` secret token
90+
91+
### Permissions
92+
- Requires `id-token: write` for PyPI trusted publishing
93+
94+
---
95+
96+
## 4. Stable Release (`release.yaml`)
97+
98+
**Trigger:** Push of any git tag
99+
100+
**Purpose:** Creates GitHub releases with auto-generated changelogs and publishes stable versions to Anaconda.
101+
102+
### Steps
103+
1. Checkout code
104+
2. **Generate Changelog:**
105+
- Uses `mikepenz/release-changelog-builder-action@v4`
106+
- Configuration from `.github/changelog-configuration.json`
107+
- Builds changelog from PRs with labels
108+
3. **Create GitHub Release:**
109+
- Uses `ncipollo/release-action@v1`
110+
- Includes generated changelog as release notes
111+
- Targets `main` branch commit
112+
4. **Build and Upload Conda Package:**
113+
- Set up Conda environment (Python 3.11)
114+
- Build with `conda build recipe/`
115+
- Upload to Anaconda using `CONDA_UPLOAD_TOKEN` secret
116+
5. **Update Wiki:**
117+
- Runs `.github/scripts/update_wiki.sh` to automatically update documentation
118+
119+
### Notes
120+
- Only runs on tagged commits (version releases)
121+
- Creates public GitHub releases visible to users
122+
- Updates project wiki documentation automatically
123+
124+
---
125+
126+
## 5. Milestone Comments (`comment-milestoned-issues.yaml`)
127+
128+
**Trigger:** When a milestone is closed
129+
130+
**Purpose:** Automatically notifies users on closed issues when their issue has been implemented in a release.
131+
132+
### Steps
133+
1. Uses `actions/github-script@v5` to run JavaScript automation
134+
2. Gets milestone number and title from the event
135+
3. Lists all issues associated with the milestone
136+
4. For each closed issue (not PRs):
137+
- Posts a comment with:
138+
- Link to the new release
139+
- Instructions to update Activity Browser
140+
- Link to subscribe to the updates mailing list
141+
- Bot disclaimer
142+
143+
### Comment Template
144+
The bot posts a formatted note:
145+
- Informs that the issue is implemented in version X
146+
- Provides update instructions
147+
- Offers subscription to updates mailing list (brightway.groups.io)
148+
- Includes bot identification
149+
150+
---
151+
152+
## Workflow Dependencies
153+
154+
### Secrets Required
155+
- `GITHUB_TOKEN` - Automatically provided by GitHub Actions
156+
- `CONDA_LCA` - Anaconda upload token for beta releases
157+
- `CONDA_UPLOAD_TOKEN` - Anaconda upload token for stable releases
158+
159+
### Configuration Files
160+
- `.github/conda-envs/build.yml` - Conda environment for building packages
161+
- `.github/changelog-configuration.json` - Changelog generation configuration
162+
- `.github/scripts/update_wiki.sh` - Wiki update script
163+
- `recipe/meta.yaml` - Conda package recipe
164+
- `pyproject.toml` - Python package configuration
165+
166+
---
167+
168+
## Development Notes
169+
170+
### Running Tests Locally
171+
To run the same tests that CI runs:
172+
```bash
173+
pip install .[testing]
174+
pytest -s --no-header --no-summary -q
175+
```
176+
177+
### Testing Matrix Changes
178+
When modifying the test matrix (OS or Python versions):
179+
- Update both `testing.yaml` and `install-canary.yaml` to keep them in sync
180+
- Consider the maintenance burden of additional combinations
181+
- Current support: Python 3.10-3.12, Ubuntu/Windows/macOS
182+
183+
### Release Process
184+
1. **Beta release:** Push to `beta` branch → Auto-publishes beta version
185+
2. **Stable release:** Create and push a tag → Creates GitHub release and publishes to Anaconda
186+
3. **Close milestone:** When closing a milestone → Users get notified automatically
187+
188+
### Monitoring
189+
- Check daily canary runs to catch dependency issues
190+
- Review failed test runs in PR checks before merging
191+
- Monitor PyPI and Anaconda Cloud for successful uploads
192+

0 commit comments

Comments
 (0)