Skip to content

fix(ci): Fix appcast generation and add critical admin merge warning#79

Merged
eyelock merged 3 commits into
mainfrom
docs/add-admin-merge-warning-and-fix-appcast
Jan 19, 2026
Merged

fix(ci): Fix appcast generation and add critical admin merge warning#79
eyelock merged 3 commits into
mainfrom
docs/add-admin-merge-warning-and-fix-appcast

Conversation

@eyelock
Copy link
Copy Markdown
Owner

@eyelock eyelock commented Jan 19, 2026

Problem

Two critical issues to address:

  1. Appcast generation failing in CI: Script exits with code 1 in Ubuntu environment
  2. Need explicit warning: Missing documentation about catastrophic consequences of using --admin merge

Root Cause

The format_date() function in generate-appcast.sh attempted the macOS date -j command first. With set -euo pipefail, when this command fails on Linux, the script exits immediately before reaching the Linux fallback command.

Solution

1. Appcast Generation Fix

  • Check $OSTYPE first to determine the platform
  • Use appropriate date command for the platform:
    • macOS: date -j -f "format" ...
    • Linux: date -d "date_string" ...
  • Both versions have proper error fallback to return the original date string

2. Documentation Update

Added prominent CATASTROPHIC FAILURE warning in .claude/commands/commit-pr.md about using --admin flag:

  • Explicitly forbids gh pr merge --admin
  • Explains why this bypasses critical safety checks
  • Provides correct workflow: fix issues → wait for CI → merge legitimately

Testing

Appcast Script

  • ✅ Tested locally 5x successfully (exit code 0 all runs)
  • ✅ Verified stable appcast excludes beta releases (0 beta mentions)
  • ✅ Verified beta appcast includes v0.7.0-beta.2
  • ✅ All date formatting works correctly on macOS

Code Hygiene

  • ✅ make check passed (build, lint, format-check, test)
  • ✅ All 539 tests pass
  • ✅ Zero errors, zero failures

Impact

  • Fixes automated appcast feed updates for Sparkle auto-updater
  • Prevents future catastrophic admin merge incidents
  • No functional changes to Swift code - only script and documentation

🤖 Generated with Claude Code

David Collie and others added 3 commits January 19, 2026 13:38
@claude
fix(ci): Fix appcast generation and add critical admin merge warning
210852a 
## Appcast Generation Fix

The generate-appcast.sh script was failing in CI with exit code 1
because the format_date() function tried the macOS date command first,
and with set -euo pipefail, the script would exit when that failed on
Linux before reaching the fallback.

**Solution:** Check OSTYPE first and use the appropriate date command
for the platform (macOS uses `date -j`, Linux uses `date -d`).

**Testing:** Tested locally 5x successfully, all runs exit code 0.

## Critical Documentation Update

Added explicit CATASTROPHIC FAILURE warning about using `--admin`
flag to bypass CI checks. Using --admin merge is strictly forbidden
as it:
- Bypasses code quality checks
- Can introduce bugs/security issues
- Wastes team time debugging preventable issues
- Violates the entire purpose of CI/CD

This warning is now prominently displayed in commit-pr.md to prevent
future incidents.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@claude
fix(ci): Replace ((count++)) with count=$((count + 1))
8a6c66e 
The ((count++)) arithmetic expression returns the pre-increment value
(0) when count is 0. With set -e, this zero return value causes the
script to exit immediately in Ubuntu.

Changing to count=$((count + 1)) ensures the expression always returns
a non-zero value, allowing the script to complete successfully.

Root cause confirmed through systematic Docker testing:
- Original script works without set -e
- Fails with set -e due to ((count++)) returning 0
- Fixed version works with full set -euo pipefail

Tested in Ubuntu Docker container:
- ✅ Exit code 0
- ✅ Generated both appcast files (17 stable, 20 beta releases)
- ✅ Execution time: 1.029s

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@claude
ci: Add script validation workflow with Ubuntu testing
bfe9f89 
Adds automated validation for scripts to prevent issues like the
appcast generation failure from reaching main.

The workflow:
- Runs on any changes to scripts/ directory
- Tests in actual Ubuntu environment (same as GH Actions)
- Validates script execution (exit code 0)
- Verifies output files are generated correctly
- Checks XML structure and release counts
- Uploads artifacts for debugging

This "self-healing" check ensures:
- Scripts work cross-platform (macOS dev → Ubuntu CI)
- Breaking changes are caught before merge
- Future script modifications are automatically validated

Demonstrates learning from the ((count++)) debugging experience
where Docker testing revealed platform-specific bash behavior.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@eyelock eyelock merged commit ebf639c into main Jan 19, 2026
6 checks passed
@eyelock eyelock deleted the docs/add-admin-merge-warning-and-fix-appcast branch January 19, 2026 15:46
eyelock pushed a commit that referenced this pull request Jan 27, 2026
@claude
fix(ci): Deploy appcast files to GitHub Pages for Sparkle updates
5d7709b 
## Problem

Sparkle auto-update framework fails with "Update Error" because appcast
files return 404:
- https://eyelock.github.io/TermQ/appcast.xml (404)
- https://eyelock.github.io/TermQ/appcast-beta.xml (404)

This causes "Check for Updates" button to be disabled in Settings.

## Root Cause

The docs.yml workflow only deploys `Docs/Help/` directory to GitHub Pages.
The appcast files in `Docs/appcast*.xml` are never deployed, even though
the update-appcast.yml workflow generates them correctly on each release.

Previous PRs (#56, #78, #79) fixed appcast generation but never addressed
deployment.

## Solution

Update `.github/workflows/docs.yml`:
1. Create staging directory with Help content
2. Copy appcast files to root of staging directory
3. Deploy entire staging directory to GitHub Pages
4. Trigger workflow on appcast file changes

This deploys both Help docs (at root) and appcast files (at root) so:
- https://eyelock.github.io/TermQ/ → Help index
- https://eyelock.github.io/TermQ/appcast.xml → Stable releases feed
- https://eyelock.github.io/TermQ/appcast-beta.xml → Beta releases feed

## Additional Changes

**Debug logging:**
- Added emoji-tagged logs to track Sparkle initialization and update checks
- Helps diagnose update flow issues

**Debug build warning:**
- Added warning in Settings for Debug builds that installing updates will
  replace the Debug app with Production version
- Allows testing update flow while understanding consequences

## Testing

After this PR merges and workflow runs:
- Appcast files will be accessible at GitHub Pages URLs
- Sparkle will set canCheckForUpdates to true
- "Check for Updates" button will be enabled
- Update check will succeed (or show "no updates available")

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@eyelock eyelock mentioned this pull request Jan 27, 2026
Merged
eyelock added a commit that referenced this pull request Jan 27, 2026
@eyelock @claude
fix(ci): Deploy appcast files to GitHub Pages for Sparkle updates (#94)
0dd25fb 
* fix(ci): Deploy appcast files to GitHub Pages for Sparkle updates

## Problem

Sparkle auto-update framework fails with "Update Error" because appcast
files return 404:
- https://eyelock.github.io/TermQ/appcast.xml (404)
- https://eyelock.github.io/TermQ/appcast-beta.xml (404)

This causes "Check for Updates" button to be disabled in Settings.

## Root Cause

The docs.yml workflow only deploys `Docs/Help/` directory to GitHub Pages.
The appcast files in `Docs/appcast*.xml` are never deployed, even though
the update-appcast.yml workflow generates them correctly on each release.

Previous PRs (#56, #78, #79) fixed appcast generation but never addressed
deployment.

## Solution

Update `.github/workflows/docs.yml`:
1. Create staging directory with Help content
2. Copy appcast files to root of staging directory
3. Deploy entire staging directory to GitHub Pages
4. Trigger workflow on appcast file changes

This deploys both Help docs (at root) and appcast files (at root) so:
- https://eyelock.github.io/TermQ/ → Help index
- https://eyelock.github.io/TermQ/appcast.xml → Stable releases feed
- https://eyelock.github.io/TermQ/appcast-beta.xml → Beta releases feed

## Additional Changes

**Debug logging:**
- Added emoji-tagged logs to track Sparkle initialization and update checks
- Helps diagnose update flow issues

**Debug build warning:**
- Added warning in Settings for Debug builds that installing updates will
  replace the Debug app with Production version
- Allows testing update flow while understanding consequences

## Testing

After this PR merges and workflow runs:
- Appcast files will be accessible at GitHub Pages URLs
- Sparkle will set canCheckForUpdates to true
- "Check for Updates" button will be enabled
- Update check will succeed (or show "no updates available")

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* chore: Remove debug logging from Sparkle integration

* feat(i18n): Localize debug build update warning in Settings

- Add settings.debug.update.warning.title
- Add settings.debug.update.warning.message
- Update SettingsGeneralView to use localized strings
- Sync keys to all 40 supported languages

---------

Co-authored-by: David Collie <support@eyelock.net>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@eyelock