# release-theme

> Execute theme release workflow. Syncs themes to sum-themes repo and creates namespaced tags. Use for "Release theme_a" requests.

- Author: Mark
- Repository: markashton480/sum_platform
- Version: 20260206154756
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/markashton480/sum_platform
- Web: https://mule.run/skillshub/@@markashton480/sum_platform~release-theme:20260206154756

---

---
name: release-theme
description: Execute theme release workflow. Syncs themes to sum-themes repo and creates namespaced tags. Use for "Release theme_a" requests.
---

# Release Theme Skill

Execute a theme release following the established workflow.

**Key points:**
- Themes are published to `markashton480/sum-themes` distribution repo
- Each theme is versioned independently using namespaced tags: `<theme_slug>/v<VERSION>`
- VERSION file is the source of truth for each theme

---

## Input

**Required:** Theme name (e.g., `theme_a`)
**Optional:** Version (e.g., `1.2.0`) - if omitted, uses VERSION file

Parse from `$ARGUMENTS`:
- `theme_a` → theme_name=theme_a, version from VERSION file
- `theme_a v1.2.0` → theme_name=theme_a, version=1.2.0
- `theme_a 1.2.0` → theme_name=theme_a, version=1.2.0

If theme name is missing, ASK the user before proceeding.

---

## Pre-Flight Checks

### 1. Run Lint and Tests

```bash
make lint && make test
```

**If either fails:** STOP and report failures before proceeding.

### 2. Verify Clean Working Tree

```bash
git status
# Should show no uncommitted changes (except untracked files)
```

**If dirty:** STOP and ask user to commit or stash changes.

### 3. Verify Theme Exists

```bash
ls -la themes/$THEME_NAME/
cat themes/$THEME_NAME/VERSION
```

**If theme doesn't exist:** STOP and report available themes.

### 4. Validate Theme Versions

```bash
python scripts/validate_theme_versions.py
```

**If validation fails:** STOP and report version mismatches.

---

## Phase 1: Determine Version

### If version provided in arguments:

Update VERSION file to match:

```bash
echo "$VERSION" > themes/$THEME_NAME/VERSION
```

If theme has `theme.json`, update its version field:

```bash
# Check if theme.json exists
if [ -f "themes/$THEME_NAME/theme.json" ]; then
  jq ".version = \"$VERSION\"" themes/$THEME_NAME/theme.json > /tmp/theme.json
  mv /tmp/theme.json themes/$THEME_NAME/theme.json
fi
```

### If no version provided:

Read from VERSION file:

```bash
VERSION=$(cat themes/$THEME_NAME/VERSION)
```

If VERSION is `0.0.0`, this is a placeholder theme - ASK user for the release version.

---

## Phase 2: Version Bump (if needed)

If version was updated, commit the change:

```bash
git add themes/$THEME_NAME/VERSION themes/$THEME_NAME/theme.json 2>/dev/null
git commit -m "chore($THEME_NAME): bump version to $VERSION"
git push origin HEAD
```

---

## Phase 3: Dry Run

Test the sync without making changes:

```bash
python scripts/publish_themes.py --dry-run
```

**Expected output:**

```
============================================================
SUM Platform -> sum-themes sync
============================================================
Dry run enabled: no commit or push will occur.

Checking source repo status...
Updating sum-themes repo...
Syncing themes...
  theme_a/ -> themes/theme_a/
  theme_b/ -> themes/theme_b/

Committing changes...
Dry run: skipping commit and push.
Pending changes:
 M themes/theme_a/VERSION
...

Sync complete.
```

Review the pending changes. If unexpected files appear, STOP and investigate.

---

## Phase 4: Sync and Commit

Run the sync script to push changes:

```bash
python scripts/publish_themes.py
```

This will:
1. Clone/update `sum-themes` to `/tmp/sum-themes-sync`
2. Copy all themes from `sum-platform/themes/` to `sum-themes/themes/`
3. Commit with message including source SHA and theme list
4. Push to `origin/main`

---

## Phase 5: Create Namespaced Tag

After publishing, create a tag in the `sum-themes` repo:

```bash
cd /tmp/sum-themes-sync

# Create annotated tag with namespace
git tag -a "$THEME_NAME/v$VERSION" -m "$THEME_NAME: Release v$VERSION

- [Add release notes here or omit for simple releases]"

# Push the tag
git push origin "$THEME_NAME/v$VERSION"
```

**Tag naming convention:**
- Format: `<theme_slug>/v<VERSION>`
- Examples: `theme_a/v1.0.0`, `theme_b/v0.5.1`

---

## Phase 6: Verification

```bash
cd /tmp/sum-themes-sync

# Verify tag exists
git ls-remote --tags origin | grep "$THEME_NAME/v$VERSION"
```

**Expected output:**

```
abc123...  refs/tags/theme_a/v1.2.0
```

---

## Phase 7: Report Success

```
Theme release complete!

Theme: $THEME_NAME
Version: $VERSION
Tag: $THEME_NAME/v$VERSION

Tag URL: https://github.com/markashton480/sum-themes/releases/tag/$THEME_NAME/v$VERSION

Clients can update via:
git subtree pull --prefix=themes/$THEME_NAME \
    git@github.com:markashton480/sum-themes.git \
    $THEME_NAME/v$VERSION --squash
```

---

## Error Handling

### Theme doesn't exist

```
Theme not found: $THEME_NAME

Available themes:
- theme_a (v0.5.0)
- theme_b (v0.0.0 - placeholder)

Please specify a valid theme name.
```

### Validation fails

```
Theme version validation failed:
- theme_a: VERSION '1.0.0' does not match theme.json version '0.9.0'

Fix VERSION/theme.json mismatch before releasing.
```

### Sync fails

```
Sync to sum-themes failed

Error: [details]

Check:
1. SSH access to sum-themes repo
2. Clean working tree
3. No conflicts

Please resolve and try again.
```

### Tag exists

```
Tag $THEME_NAME/v$VERSION already exists

Options:
1. Use next patch version (e.g., v$VERSION_PATCH)
2. Investigate why tag exists

Reply with choice.
```

---

## Rollback Procedure

### Option A: Publish a fix (recommended)

1. Fix the issue in `sum-platform/themes/<theme>/`
2. Bump the patch version (e.g., 1.2.0 -> 1.2.1)
3. Run this skill again

### Option B: Delete the bad tag (if no clients consumed it)

```bash
cd /tmp/sum-themes-sync

# Delete remote tag
git push origin --delete $THEME_NAME/v$VERSION

# Delete local tag
git tag -d $THEME_NAME/v$VERSION
```

**Note:** Tags are immutable. Never re-tag the same version - always increment.

---

## Safety Rules

1. **Never re-tag existing versions** - Create new patch version instead
2. **Always run dry-run first** - Review changes before publishing
3. **Validate before publish** - `validate_theme_versions.py` must pass
4. **Clean working tree required** - Commit or stash changes first