csst.at-extension/RELEASE.md

Release Guide

This document explains how to create and manage releases for the Leetify Extension plugin.

📋 Overview

The project supports two types of releases:

1. Automated Releases - Using GitHub Actions and semantic-release
2. Manual Releases - Using local scripts for more control

🤖 Automated Releases (Recommended)

Prerequisites

• Repository must be hosted on GitHub
• GITHUB_TOKEN secret must be configured in repository settings
• All changes committed to main or master branch

How it Works

1. Commit Messages: Use Conventional Commits format:

   feat: add new Leetify integration feature
   fix: resolve profile loading issue
   docs: update installation instructions
   chore: update dependencies
   

2. Automatic Triggering: Releases are triggered automatically when:

   • Commits are pushed to main/master branch
   • Commit messages follow conventional format
   • Changes affect code (not just documentation)

3. Version Bumping: Semantic-release automatically determines version based on commit types:

   • fix: → Patch release (1.0.0 → 1.0.1)
   • feat: → Minor release (1.0.0 → 1.1.0)
   • BREAKING CHANGE: → Major release (1.0.0 → 2.0.0)

Setting Up Automated Releases

1. Configure GitHub Secrets:

   • Go to your repository → Settings → Secrets and variables → Actions
   • Add GITHUB_TOKEN (usually automatically available)

2. Make a Release Commit:

   git add .
   git commit -m "feat: add Leetify profile integration"
   git push origin main
   ```
   
   

3. Monitor Release:

   • Check Actions tab in GitHub for release progress
   • Release will appear in Releases section when complete

🔧 Manual Releases

Prerequisites

• Node.js 18+ with pnpm installed
• Python 3.7+ with pip
• Git repository with clean working directory

Creating a Manual Release

1. Install Dependencies:

   pnpm install
   pip install -r requirements.txt
   

2. Run Release Script:

   # Patch release (1.0.0 → 1.0.1)\n   pnpm run release patch\n   \n   # Minor release (1.0.0 → 1.1.0)\n   pnpm run release minor\n   \n   # Major release (1.0.0 → 2.0.0)\n   pnpm run release major\n   ```\n\n3. **Push Changes**:\n   ```bash\n   git push origin main\n   git push origin v<version>\n   ```\n\n4. **Create GitHub Release**:\n   - Go to GitHub → Releases → \"Create a new release\"\n   - Select the tag created by the script\n   - Upload the generated ZIP file from `build/` directory\n   - Add release notes\n\n### Available Scripts\n\n```bash\n# Build plugin package\npnpm run build-plugin\n\n# Create manual release\npnpm run release <patch|minor|major>\n\n# Sync versions between files\npnpm run sync-version <version>\n\n# Development build\npnpm run dev\n\n# Production build\npnpm run build\n```\n\n## 📦 Release Artifacts\n\nEach release creates:\n- **ZIP Package**: `leetify-extension-v<version>.zip`\n- **Updated Files**: `package.json`, `plugin.json`, `CHANGELOG.md`\n- **Git Tag**: `v<version>`\n- **GitHub Release**: With ZIP attachment and release notes\n\n### Package Contents\n```\nleetify-extension-v1.0.0.zip\n├── frontend/          # React frontend components\n├── webkit/           # Steam webkit integration\n├── backend/          # Python backend logic\n├── styles/           # CSS styles\n├── dist/            # Built assets (if exists)\n├── package.json     # Node.js package configuration\n├── plugin.json      # Millennium plugin configuration\n├── requirements.txt # Python dependencies\n├── README.md        # Installation and usage guide\n└── LICENSE          # License file\n```\n\n## 🔄 Version Management\n\n### Version Synchronization\nThe release system automatically keeps versions synchronized across:\n- `package.json` - Node.js package version\n- `plugin.json` - Millennium plugin version\n\n### Version Scheme\nFollows [Semantic Versioning](https://semver.org/):\n- **MAJOR** (X.0.0): Breaking changes, incompatible API changes\n- **MINOR** (0.X.0): New features, backwards compatible\n- **PATCH** (0.0.X): Bug fixes, backwards compatible\n\n## 🚀 Deployment Process\n\n### For Plugin Users\n1. Download latest release ZIP from GitHub Releases\n2. Extract to Steam plugins directory\n3. Enable plugin in Millennium settings\n4. Restart Steam\n\n### For Developers\n1. Clone repository\n2. Install dependencies\n3. Make changes\n4. Create release (automated or manual)\n5. Users download and install\n\n## 🛠️ Troubleshooting\n\n### Common Issues\n\n**Build Fails**:\n```bash\n# Clear cache and reinstall\npnpm clean-install\npip install --upgrade -r requirements.txt\n```\n\n**Version Sync Issues**:\n```bash\n# Manually sync versions\npnpm run sync-version 1.2.3\n```\n\n**Git Tag Conflicts**:\n```bash\n# Delete local tag\ngit tag -d v1.0.0\n\n# Delete remote tag\ngit push origin :refs/tags/v1.0.0\n```\n\n**Release Workflow Fails**:\n- Check GitHub Actions logs\n- Verify secrets are configured\n- Ensure commit messages follow conventional format\n- Check for merge conflicts\n\n### Debug Mode\n```bash\n# Enable verbose logging\nexport DEBUG=semantic-release:*\npnpm run release patch\n```\n\n## 📋 Release Checklist\n\n### Before Release\n- [ ] All tests pass\n- [ ] Documentation is updated\n- [ ] CHANGELOG.md reflects changes\n- [ ] Version compatibility verified\n- [ ] No uncommitted changes\n\n### During Release\n- [ ] Choose appropriate version bump\n- [ ] Verify build completes successfully\n- [ ] Check generated ZIP contains all files\n- [ ] Validate plugin.json and package.json versions match\n\n### After Release\n- [ ] GitHub release created successfully\n- [ ] ZIP file uploaded to release\n- [ ] Release notes are accurate\n- [ ] Installation instructions updated if needed\n- [ ] Community notified (if applicable)\n\n## 🔗 Related Links\n\n- [Conventional Commits](https://www.conventionalcommits.org/)\n- [Semantic Versioning](https://semver.org/)\n- [GitHub Actions Documentation](https://docs.github.com/en/actions)\n- [Millennium Plugin Documentation](https://docs.steambrew.app/developers/plugins/learn)\n\n---\n\n**Note**: This release system is designed specifically for Millennium plugins and follows the framework's conventions and requirements.