pymc_console-dist/RELEASE.md

pyMC UI Release Guide

Complete guide for developers to create and publish new releases of the pyMC UI.

Table of Contents

• Quick Release Steps
• Understanding the Release Process
• Manual Build Process
• Troubleshooting
• Version Numbering

---

Quick Release Steps

For experienced developers, here's the TL;DR:

cd pymc_console/frontend

# 1. Update version (creates git tag automatically if configured)
npm version patch

# 2. Push changes and tag
git push origin main
git push origin --tags

# Done! Check GitHub Actions for build status

---

Understanding the Release Process

What Happens Automatically

This project uses GitHub Actions for continuous integration and deployment:

On Every Push to main or dev:

• ✅ Installs dependencies
• ✅ Builds static files (npm run build:static)
• ✅ Creates versioned .tar.gz and .zip archives
• ✅ Uploads build artifacts to GitHub (available for 30 days)
• ❌ Does NOT create a GitHub Release

On Version Tag Push (e.g., v0.1.1):

• ✅ Everything above, PLUS
• ✅ Creates a GitHub Release
• ✅ Attaches downloadable archives to the release
• ✅ Generates automatic release notes from commits

The Workflow File

Located at: .github/workflows/build-ui.yml

This workflow has two jobs:

1. build - Runs on all pushes and PRs
2. release - Only runs when a tag starting with v is pushed

---

Detailed Release Steps

Step 1: Make Your Changes

Work on your feature branch as normal:

git checkout -b feature/my-new-feature
# ... make changes ...
git add .
git commit -m "feat: add awesome new feature"
git push origin feature/my-new-feature

Create a PR, get it reviewed, and merge to main.

Step 2: Decide on Version Number

Use Semantic Versioning:

• MAJOR (1.0.0 → 2.0.0) - Breaking changes
• MINOR (0.1.0 → 0.2.0) - New features, backwards compatible
• PATCH (0.1.1 → 0.1.2) - Bug fixes only

Step 3: Update Version

Navigate to the frontend directory:

cd pymc_console/frontend

Run the appropriate npm version command:

# For bug fixes
npm version patch

# For new features
npm version minor

# For breaking changes
npm version major

# For pre-releases
npm version prerelease --preid=beta

What this does:

• Updates version in package.json and package-lock.json
• Creates a git commit with message like "0.1.2"
• Creates a git tag like v0.1.2 (if git is configured properly)

Step 4: Push Changes and Tags

Push your version commit:

git push origin main

Push the tag to trigger the release:

git push origin --tags

Or push a specific tag:

git push origin v0.1.2

Step 5: Monitor the Release

1. Go to your repository on GitHub
2. Click the Actions tab
3. You should see a workflow running for your tag
4. Wait for both jobs (build and release) to complete

Step 6: Verify the Release

Once the workflow completes:

1. Go to the Releases section of your GitHub repo
2. You should see your new release (e.g., v0.1.2)
3. It should have two attached files:
   • pymc-ui-v0.1.2.tar.gz
   • pymc-ui-v0.1.2.zip
4. Release notes are auto-generated from commit messages

---

Manual Build Process

If you need to build locally without creating a release:

cd pymc_console/frontend

# Install dependencies (first time only)
npm install

# Build static files
npm run build:static

The output will be in frontend/dist/ directory.

What the Build Does

1. vite build - Compiles React app to static HTML/CSS/JS
2. Outputs to frontend/out/
3. Copies out/ contents to frontend/dist/

---

Troubleshooting

"Release job was skipped"

Problem: You pushed code but no GitHub Release was created.

Solution: The release job only runs for version tags. Make sure you:

1. Created a tag with npm version or git tag v0.1.x
2. Pushed the tag with git push origin --tags
3. The tag name starts with v (e.g., v0.1.2, not 0.1.2)

"Build failed: npm ERR! code ELIFECYCLE"

Problem: The build process failed.

Solution:

1. Pull the latest code: git pull origin main
2. Clean install locally: cd frontend && rm -rf node_modules package-lock.json && npm install
3. Test build locally: npm run build:static
4. Fix any errors before pushing

"Tag already exists"

Problem: You tried to create a tag that already exists.

Solution:

# Delete local tag
git tag -d v0.1.2

# Delete remote tag (if already pushed)
git push origin :refs/tags/v0.1.2

# Create new tag
npm version patch
git push origin --tags

"Permission denied" when creating release

Problem: GitHub Actions doesn't have permission to create releases.

Solution: The workflow already has permissions: contents: write set. Check your repository settings:

1. Go to Settings → Actions → General
2. Under "Workflow permissions", ensure "Read and write permissions" is selected

---

Version Numbering

Semantic Versioning Format

MAJOR.MINOR.PATCH (e.g., 0.1.2)

When to Increment Each Part

Change Type	Example	Command	Version Change
Bug fix	Fix broken map display	npm version patch	0.1.1 → 0.1.2
New feature	Add dark mode	npm version minor	0.1.2 → 0.2.0
Breaking change	Require new API version	npm version major	0.2.0 → 1.0.0
Pre-release	Beta testing	npm version prerelease --preid=beta	0.1.2 → 0.1.3-beta.0

Pre-release Tags

For alpha, beta, or release candidate versions:

# First beta
npm version 0.2.0-beta.1

# Subsequent betas
npm version prerelease --preid=beta  # 0.2.0-beta.2

# Release candidate
npm version 0.2.0-rc.1

# Final release
npm version 0.2.0

Pre-releases are automatically marked as "Pre-release" on GitHub.

---

End User Deployment

Once a release is published, end users can deploy it:

Download and Extract

# Download latest release
wget https://github.com/dmduran12/pymc_console/releases/download/v0.2.0/pymc-ui-v0.2.0.tar.gz

# Extract to pyMC_Repeater's web directory
tar -xzf pymc-ui-v0.2.0.tar.gz -C /opt/pymc_repeater/repeater/web/html/

# Or use zip
unzip pymc-ui-v0.2.0.zip -d /opt/pymc_repeater/repeater/web/html/

Configure Backend

The backend (pyMC_API) should be configured to serve these static files. Users control where they deploy the UI files.

---

Quick Reference Commands

# View current version
cat frontend/package.json | grep version

# List all tags
git tag --list

# View latest tag
git describe --tags --abbrev=0

# Delete local tag
git tag -d v0.1.2

# Delete remote tag
git push origin :refs/tags/v0.1.2

# Create tag manually (if npm version didn't work)
git tag v0.1.2
git push origin v0.1.2

# Check GitHub Actions status
# Visit: https://github.com/dmduran12/pymc_console/actions

---

Need Help?

• Check GitHub Actions logs for detailed error messages
• Review commit messages to ensure they follow conventions
• Test builds locally before pushing tags
• Ask in the project's discussion forum or issues section