release

docs/release.md

@@ -18,6 +18,7 @@ To use the release automation, you need:
 - Git installed locally
 - GitHub CLI installed and authenticated
 - Proper GitHub permissions on the repository
+- Optional: `act` for local testing (https://github.com/nektos/act)
 
 ## Starting a Release
 
@@ -44,6 +45,36 @@ npm run release minor "Added DLC management feature and improved UI"
 
 If you don't provide custom notes, they will be automatically generated from commit messages since the last release.
 
+### Advanced Options
+
+The release script supports several advanced options:
+
+#### Dry Run
+
+Run the release process without actually creating a release:
+
+```bash
+npm run release patch --dry-run
+```
+
+This will perform all the version incrementing and workflow steps but won't create the actual GitHub release.
+
+#### Local Testing
+
+Test the workflow locally before running it on GitHub:
+
+```bash
+npm run release minor --local
+```
+
+This requires the `act` tool to be installed (https://github.com/nektos/act) and runs the workflow locally to check for errors.
+
+You can combine options:
+
+```bash
+npm run release patch --local --dry-run
+```
+
 ### Method 2: Manually triggering the workflow in GitHub
 
 You can also manually trigger the workflow from the GitHub Actions tab:
@@ -54,7 +85,8 @@ You can also manually trigger the workflow from the GitHub Actions tab:
 4. Click "Run workflow"
 5. Choose the version increment type (patch, minor, major)
 6. Optionally enter custom release notes
-7. Click "Run workflow"
+7. Check the "dry run" option if you want to test without creating a release
+8. Click "Run workflow"
 
 ## Release Process Details
 
@@ -70,10 +102,19 @@ The release process follows these steps:
    - Commits the version changes
    - Creates a version tag
    - Pushes the changes and tag to the repository
-5. **Release Creation**: Creates a GitHub Release with the changelog
-6. **Build Process**: Builds the application for Linux
+5. **Build Process**: Builds the application for Linux (and potentially other platforms)
+6. **Release Creation**: Creates a GitHub Release with the changelog after all builds are complete
 7. **Asset Upload**: Uploads the AppImage and Debian package to the release
 
+## Optimizations
+
+The release workflow includes several optimizations:
+
+- **Caching**: Uses Rust and npm caches to speed up build times
+- **Parallel Builds**: Builds for different platforms in parallel
+- **Artifact Management**: Properly manages build artifacts between jobs
+- **Error Handling**: Improves error detection and reporting
+
 ## Release Artifacts
 
 The following artifacts are published to the GitHub release:
@@ -94,7 +135,15 @@ CreamLinux follows [Semantic Versioning](https://semver.org/):
 If you encounter issues with the release process:
 
 1. **Check GitHub Actions logs**: Review the workflow logs for detailed error information
-2. **Verify permissions**: Ensure you have write permissions to the repository
-3. **GitHub CLI authentication**: Run `gh auth status` to verify authentication
+2. **Use local testing**: Run with `--local` flag to test locally before triggering on GitHub
+3. **Try dry run mode**: Use `--dry-run` to test the process without creating an actual release
+4. **Verify permissions**: Ensure you have write permissions to the repository
+5. **GitHub CLI authentication**: Run `gh auth status` to verify authentication
+
+Common errors:
+
+- **"act not found"**: Install the `act` tool for local testing
+- **Upload errors**: Check if the build produced the expected artifacts
+- **Permission errors**: Check GitHub permissions and token access
 
 For technical issues with the release workflow, contact the CreamLinux maintainers.