githubnext / githubnext/autoloop
Basic versioning: VERSION file + self-check that opens an update-available issue on drift
- Dominant language
- Python
- Stars
- 71
- Forks
- 6
- PR merge metrics
- No merged PRs in 30d
Description
## Summary
Autoloop has no versioning today — no tags, no releases, no `VERSION` file. `install.md` clones `main` directly with no SHA pin, and `gh aw add-wizard` isn't a viable install path because the Autoloop install needs custom steps beyond what the wizard handles.
Result: installed copies of Autoloop drift silently from upstream. Users have no way to know they're behind, no way to see what changed, and no prompt to upgrade.
Propose a minimal versioning scheme: a plain version string in this repo, and a small self-check the installed Autoloop workflow runs on every execution. When the installed version doesn't match upstream, the workflow opens an issue in the consuming repo with a link to the diff. That's it — no CI tooling, no releases ceremony, no dependency on `gh aw add`.
## Design
### 1. Plain `VERSION` file at the repo root
```
0.1.0
```
Bump it on any change to `workflows/autoloop.md`, `workflows/sync-branches.md`, `workflows/shared/**`, or `.github/ISSUE_TEMPLATE/autoloop-program.md`. Semver-ish, but don't over-engineer — even a monotonic integer would work. A human maintainer updates it when they merge a change they'd want consumers to notice. No automation needed.
Ship an adjacent `CHANGELOG.md` that lists what changed per version. Doesn't need to be exhaustive — one line per version is fine. The point is "if you're on 0.1.3 and upstream is 0.2.0, here's what happened between."
### 2. `install.md` records the installed version
Update `install.md` to copy `VERSION` into the consuming repo alongside the workflow files:
```bash
cp /tmp/autoloop/VERSION .github/autoloop-version
```
(Path is `.github/autoloop-version` rather than e.g. `.autoloop/VERSION` because `.github/` is the natural home for meta-files about workflows in this repo, and keeping it out of `.autoloop/` avoids conflating it with program definitions.)
### 3. Version check in the autoloop workflow pre-step
Add a step near the top of the autoloop workflow that:
1. Reads the locally installed version from `.github/autoloop-version`.
2. Fetches upstream's current `VERSION` from `https://raw.githubusercontent.com/githubnext/autoloop/main/VERSION`.
3. If they differ, checks whether an open "update available" issue already exists (dedupe by a stable title or label).
4. If no such issue exists, opens one with a link to the diff and the changelog.
Concrete implementation sketch:
```yaml
- name: Check for Autoloop upstream updates
env:
GITHUB_TOKEN: ${{ github.token }}
GITHUB_REPOSITORY: ${{ github.repository }}
run: |
set -euo pipefail
LOCAL_VERSION_FILE=".github/autoloop-version"
UPSTREAM_URL="https://raw.githubusercontent.com/githubnext/autoloop/main/VERSION"
if [ ! -f "$LOCAL_VERSION_FILE" ]; then
echo "No local autoloop-version file; skipping drift check."
exit 0
fi
LOCAL=$(tr -d '[:space:]' < "$LOCAL_VERSION_FILE")
UPSTREAM=$(curl -fsSL "$UPSTREAM_URL" 2>/dev/null | tr -d '[:space:]' || echo "")
if [ -z "$UPSTREAM" ] || [ "$LOCAL" = "$UPSTREAM" ]; then
echo "Autoloop up to date (local=$LOCAL, upstream=$UPSTREAM)."
exit 0
fi
echo "Autoloop is behind: local=$LOCAL, upstream=$UPSTREAM"
# Dedupe: don't open a new issue if one is already open for this drift.
EXISTING=$(gh issue list \
--repo "$GITHUB_REPOSITORY" \
--label "autoloop-update-available" \
--state open \
--search "in:title \"$UPSTREAM\"" \
--json number \
--jq '.[0].number // empty')
if [ -n "$EXISTING" ]; then
echo "Existing update-available issue #$EXISTING already open for $UPSTREAM."
exit 0
fi
gh issue create \
--repo "$GITHUB_REPOSITORY" \
--title "[Autoloop] Update available: $LOCAL → $UPSTREAM" \
--label "autoloop-update-available,automation,autoloop" \
--body "$(cat <
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.