# Release v1.2.1 Instructions

> This release-specific guide complements the general [PyPI Release Process](../PYPI_RELEASE.md) documentation.

## Status: Ready to Release ✅

The repository is fully prepared for v1.2.1 release with coordinated workflows.

## What Was Changed

### Workflow Coordination

- Added `release: types: [published]` trigger to `.github/workflows/build-executables.yml`
- This ensures both `publish-pypi.yml` and `build-executables.yml` trigger on the same release event
- Both workflows now work together to create a complete release

### Version Verification

- ✅ `pyproject.toml` version: `1.2.1`
- ✅ `scripts/__init__.py` version: `1.2.1`
- ✅ Versions are consistent and ready for release

## How to Release v1.2.1

### Option 1: Manual Release (Recommended for v1.2.1)

Since the version is already set to 1.2.1, simply create a GitHub release:

1. **Go to GitHub Releases:**

   - Navigate to https://github.com/saint2706/Games/releases/new

1. **Create the Release:**

   - Tag: `v1.2.1`
   - Release title: `v1.2.1`
   - Description: Add your release notes (see CHANGELOG.md for reference)
   - Click "Publish release"

1. **Watch the Magic:**
   Both workflows will automatically trigger and run in parallel:

   - **`publish-pypi.yml`:**

     - ✅ Validates version consistency
     - ✅ Builds wheel and source distribution
     - ✅ Publishes to PyPI
     - ✅ Signs packages with Sigstore
     - ✅ Uploads to GitHub Release

   - **`build-executables.yml`:**

     - ✅ Builds executables for Linux, Windows, macOS
     - ✅ Runs cross-platform tests
     - ✅ Uploads executables to GitHub Release

1. **Verify the Release:**
   After both workflows complete (typically 10-15 minutes), check the release has:

   - Distribution packages: `games_collection-1.2.1-py3-none-any.whl`, `games_collection-1.2.1.tar.gz`
   - Signatures: `.sigstore` files
   - Executables:
     - `games-collection` (Linux)
     - `games-collection.exe` (Windows)
     - `games-collection` (macOS)

1. **Verify PyPI:**

   - Visit https://pypi.org/project/games-collection/
   - Confirm version 1.2.1 is published
   - Test installation: `pip install --upgrade games-collection==1.2.1`

### Option 2: Automated Workflow Trigger

If you want to use the automated workflow for future releases:

1. Go to Actions → "Publish to PyPI" → "Run workflow"
1. Select branch: `master`
1. Choose version bump type (for future releases after 1.2.1)
1. Click "Run workflow"

**Note:** Don't use this for v1.2.1 since the version is already set. This is for future releases.

## What Happens When You Trigger the Release

```
┌─────────────────────────────────────┐
│  You create GitHub Release v1.2.1  │
└──────────────┬──────────────────────┘
               │
               │ triggers both workflows
               │
       ┌───────┴────────┐
       │                │
       ▼                ▼
┌──────────┐    ┌───────────┐
│ publish- │    │   build-  │
│ pypi.yml │    │executables│
└────┬─────┘    └─────┬─────┘
     │                │
     │                │
     ├─ Validate      ├─ Build Linux
     ├─ Build dist    ├─ Build Windows
     ├─ Publish PyPI  ├─ Build macOS
     ├─ Sign          ├─ Test all
     └─ Upload        └─ Upload
         │                │
         └────────┬───────┘
                  │
                  ▼
         ┌────────────────┐
         │ Complete Release│
         │  All Artifacts  │
         └────────────────┘
```

## Monitoring the Release

1. **GitHub Actions:**

   - Go to https://github.com/saint2706/Games/actions
   - You'll see two workflow runs triggered by your release
   - Monitor their progress (both should complete successfully)

1. **Common Issues:**

   - If workflows fail, check the logs in Actions tab
   - Ensure PyPI trusted publishing is configured (see docs/deployment/PYPI_RELEASE.md)
   - Ensure GitHub environment `pypi` exists (see Prerequisites in PYPI_RELEASE.md)

## Post-Release Verification

After the release completes:

1. **Check GitHub Release:**

   ```bash
   # View the release
   open https://github.com/saint2706/Games/releases/tag/v1.2.1
   ```

1. **Check PyPI:**

   ```bash
   # Search for the package
   pip search games-collection  # (if pip search is available)
   # Or visit: https://pypi.org/project/games-collection/1.2.1/
   ```

1. **Test Installation:**

   ```bash
   # Create a new virtual environment
   python -m venv test_env
   source test_env/bin/activate  # On Windows: test_env\Scripts\activate

   # Install the new version
   pip install games-collection==1.2.1

   # Test the launcher
   games-collection --help

   # Test a specific game
   games-uno --help
   ```

1. **Download and Test Executable:**

   - Download the executable for your platform from the GitHub Release
   - Run it to ensure it works
   - Linux/macOS: `chmod +x games-collection && ./games-collection`
   - Windows: Double-click `games-collection.exe`

## Documentation

For more details, see:

- `docs/deployment/PYPI_RELEASE.md` - Complete PyPI release process
- `docs/development/BUILD_EXECUTABLES_WORKFLOW.md` - Executable building details
- `CHANGELOG.md` - Version history and changes

## Troubleshooting

### Workflow Fails

- Check workflow logs in Actions tab
- Verify all prerequisites are met (PyPI trusted publishing, GitHub environment)
- Ensure version consistency (`python scripts/check_version_consistency.py --tag v1.2.1`)

### PyPI Upload Fails

- Check that version 1.2.1 doesn't already exist on PyPI
- Verify PyPI trusted publishing is configured correctly
- Ensure the `pypi` environment exists in GitHub repository settings

### Executables Not Uploaded

- Check that `build-executables.yml` workflow completed successfully
- Verify all three platforms (Linux, Windows, macOS) built successfully
- Check workflow logs for any errors

## Next Steps After v1.2.1

For future releases:

1. Update CHANGELOG.md with new changes
1. Use the automated workflow (Option 1) to bump version and create release
1. Both workflows will automatically handle everything
1. The coordination is now permanent - every release will have both PyPI package and executables

## Questions?

If you encounter any issues:

1. Check the workflow logs in the Actions tab
1. Review the documentation in `docs/deployment/`
1. Verify prerequisites are met
1. The workflows are designed to provide clear error messages

______________________________________________________________________

**Ready to release? Just create the GitHub release and watch the automation work! 🚀**
