Skip to content

Release Process

Jump to bottom
Calvindd2f edited this page Jan 14, 2026 · 1 revision

Release Process

Relevant source files

The following files were used as context for generating this wiki page:

This document describes the complete release workflow for OfficeScrubC2R, including version management, artifact preparation, validation steps, and publication to PowerShell Gallery and GitHub Releases. This process is designed for maintainers preparing official releases.

For information about contributing code changes, see Development Guidelines. For information about the CI/CD pipeline that validates changes, see CI/CD Pipeline.

Version Management

Semantic Versioning Strategy

OfficeScrubC2R follows Semantic Versioning 2.0.0 with the format MAJOR.MINOR.PATCH:

Component Increment When Example
MAJOR Breaking changes that affect API compatibility 2.19.0 → 3.0.0
MINOR New features added in a backward-compatible manner 3.0.0 → 3.1.0
PATCH Backward-compatible bug fixes 3.1.0 → 3.1.1

Version Location: OfficeScrubC2R.psd1:6

ModuleVersion = '3.0.0'

Version Decision Tree

flowchart TD
    Start["Changes Ready for Release"] --> Breaking{"Breaking Changes?"}
    
    Breaking -->|Yes| Major["Increment MAJOR<br/>Reset MINOR and PATCH to 0"]
    Breaking -->|No| Features{"New Features?"}
    
    Features -->|Yes| Minor["Increment MINOR<br/>Reset PATCH to 0"]
    Features -->|No| Fixes{"Bug Fixes Only?"}
    
    Fixes -->|Yes| Patch["Increment PATCH"]
    Fixes -->|No| NoChange["No Release Needed"]
    
    Major --> Example1["Example: 2.19.2 → 3.0.0"]
    Minor --> Example2["Example: 3.0.0 → 3.1.0"]
    Patch --> Example3["Example: 3.1.0 → 3.1.1"]
    
    Example1 --> Validate["Proceed to Release Validation"]
    Example2 --> Validate
    Example3 --> Validate
Loading

Breaking Changes Include:

  • Removing or renaming exported functions
  • Changing function parameter names or types
  • Modifying native DLL interface
  • Removing support for PowerShell versions

Sources: CONTRIBUTING.md:184-191, OfficeScrubC2R.psd1:6

Pre-Release Checklist

Before initiating a release, verify all prerequisites are met:

Code Readiness

Requirement Validation Command Expected Result
All tests pass Invoke-Pester 0 failures
PSScriptAnalyzer clean Invoke-ScriptAnalyzer -Path . -Recurse No errors or warnings
Native DLL builds .\build.ps1 OfficeScrubNative.dll created
Module imports Import-Module .\OfficeScrubC2R.psd1 -Force No errors
Manifest valid Test-ModuleManifest .\OfficeScrubC2R.psd1 Returns manifest object

Documentation Completeness

File Verification

Required files must exist and be unblocked:

# Check required files
$requiredFiles = @(
    'OfficeScrubC2R.psd1',
    'OfficeScrubC2R.psm1',
    'OfficeScrubNative.dll',
    'LICENSE',
    'README.md'
)

foreach ($file in $requiredFiles) {
    if (-not (Test-Path $file)) {
        throw "Required file missing: $file"
    }
}

Sources: .github/workflows/ci.yml:84-99, OfficeScrubC2R.psd1:82-91

Release Workflow

flowchart TB
    Start["Start Release Process"] --> UpdateVer["Update ModuleVersion in<br/>OfficeScrubC2R.psd1"]
    
    UpdateVer --> UpdateChange["Update CHANGELOG.md<br/>Add version section with changes"]
    
    UpdateChange --> UpdateNotes["Update ReleaseNotes in<br/>OfficeScrubC2R.psd1"]
    
    UpdateNotes --> Build["Run build.ps1<br/>Compile OfficeScrubNative.dll"]
    
    Build --> TestLocal["Local Testing<br/>Import-Module and validate"]
    
    TestLocal --> Pass{"Tests Pass?"}
    Pass -->|No| Fix["Fix Issues"]
    Fix --> Build
    
    Pass -->|Yes| Commit["git commit -m 'Release vX.Y.Z'"]
    
    Commit --> Tag["git tag -a vX.Y.Z -m 'Release vX.Y.Z'"]
    
    Tag --> Push["git push origin main<br/>git push --tags"]
    
    Push --> CI["CI Pipeline Executes<br/>Test and Validate Jobs"]
    
    CI --> CIPass{"CI Pass?"}
    CIPass -->|No| DeleteTag["Delete tag<br/>Fix issues"]
    DeleteTag --> Fix
    
    CIPass -->|Yes| GHRelease["Create GitHub Release<br/>Attach artifacts"]
    
    GHRelease --> PSGallery["Publish to PowerShell Gallery<br/>Publish-Module"]
    
    PSGallery --> Verify["Verify Installation<br/>Install-Module OfficeScrubC2R"]
    
    Verify --> Announce["Announce Release<br/>Update README badge"]
Loading

Sources: CONTRIBUTING.md:192-211, .github/workflows/ci.yml:1-109

Step-by-Step Release Procedure

Step 1: Update Version Number

Edit OfficeScrubC2R.psd1:6 to increment the version:

# Before
ModuleVersion = '3.0.0'

# After (example for minor release)
ModuleVersion = '3.1.0'

Step 2: Update CHANGELOG.md

Add a new version section at the top of CHANGELOG.md following the Keep a Changelog format:

## [3.1.0] - 2025-01-15

### Added
- New feature X for improved performance
- Support for additional Office products

### Changed
- Optimized registry cleanup algorithm

### Fixed
- Issue with WOW64 registry handling in specific scenarios

Format Sections:

  • Added - New features
  • Changed - Changes to existing functionality
  • Deprecated - Soon-to-be-removed features
  • Removed - Removed features
  • Fixed - Bug fixes
  • Security - Security-related changes

Sources: CHANGELOG.md:1-6, CONTRIBUTING.md:159

Step 3: Update Release Notes in Manifest

Edit the ReleaseNotes field in OfficeScrubC2R.psd1:124-137:

ReleaseNotes = @'
# Release Notes v3.1.0

## Overview
This release adds support for additional Office products and improves performance.

## What's New
- Feature X with 25% faster execution
- Support for Office 2024 detection
- Enhanced error reporting

## Breaking Changes
None

## Bug Fixes
- Fixed WOW64 registry handling edge case
'@

Step 4: Build and Test

# Clean build
.\build.ps1 -Clean

# Verify DLL created
if (-not (Test-Path ".\OfficeScrubNative.dll")) {
    throw "DLL build failed"
}

# Test manifest
$manifest = Test-ModuleManifest -Path .\OfficeScrubC2R.psd1
Write-Host "Version: $($manifest.Version)"

# Import module
Import-Module .\OfficeScrubC2R.psd1 -Force -Verbose

# Run basic validation
Get-Command -Module OfficeScrubC2R

Sources: .github/workflows/ci.yml:24-37

Step 5: Commit and Tag

# Stage changes
git add OfficeScrubC2R.psd1 CHANGELOG.md OfficeScrubNative.dll

# Commit with descriptive message
git commit -m "Release v3.1.0

- Add feature X
- Improve performance
- Fix WOW64 issue
"

# Create annotated tag
git tag -a v3.1.0 -m "Release v3.1.0"

# Push commits and tags
git push origin main
git push --tags

Tag Format: v{MAJOR}.{MINOR}.{PATCH} (e.g., v3.1.0)

Sources: CONTRIBUTING.md:194-199

CI/CD Validation

Upon pushing tags, the GitHub Actions CI pipeline executes automatically.

CI Pipeline Jobs

flowchart LR
    Push["git push --tags"] --> Trigger["GitHub Actions Triggered"]
    
    Trigger --> TestJob["Test Job"]
    Trigger --> ValidateJob["Validate Job"]
    
    TestJob --> T1["Build Native DLL"]
    T1 --> T2["Test Module Import"]
    T2 --> T3["Test Functions"]
    T3 --> T4["Validate Manifest"]
    
    ValidateJob --> V1["Build DLL"]
    V1 --> V2["Test Manifest"]
    V2 --> V3["Check Required Files"]
    V3 --> V4["Verify No Blocked Files"]
    
    T4 --> Success{"All Checks Pass?"}
    V4 --> Success
    
    Success -->|Yes| Proceed["Proceed to GitHub Release"]
    Success -->|No| Fail["Fix Issues and Re-tag"]
Loading

Test Job Validation (.github/workflows/ci.yml:11-63):

  1. Checkout code
  2. Setup PowerShell environment
  3. Build OfficeScrubNative.dll via build.ps1
  4. Import module and verify commands available
  5. Test function availability
  6. Validate manifest structure

Validate Job Validation (.github/workflows/ci.yml:64-109):

  1. Build DLL
  2. Test manifest with Test-ModuleManifest
  3. Verify all required files exist
  4. Check for Zone.Identifier streams (blocked files)

Required Files (.github/workflows/ci.yml:87-93):

  • OfficeScrubC2R.psd1
  • OfficeScrubC2R.psm1
  • OfficeScrubNative.dll
  • LICENSE
  • README.md

Sources: .github/workflows/ci.yml:1-109

GitHub Release Creation

After CI validation passes, create a GitHub Release:

Release Creation Steps

  1. Navigate to https://github.com/Calvindd2f/OfficeScrubC2R/releases/new
  2. Select the tag (e.g., v3.1.0)
  3. Set release title: v3.1.0 (matches tag)
  4. Copy release notes from OfficeScrubC2R.psd1:124-137 into description
  5. Attach artifacts (optional):
    • OfficeScrubNative.dll
    • Full module package (zipped)
  6. Mark as "Latest release" (or "Pre-release" if beta)
  7. Click "Publish release"

GitHub Release Artifact Structure

OfficeScrubC2R-v3.1.0.zip
├── OfficeScrubC2R.psd1
├── OfficeScrubC2R.psm1
├── OfficeScrubNative.dll
├── OfficeScrubC2R-Native.cs
├── direct_conversion.cs
├── docs/
│   └── source/
│       └── OfficeScrubC2R.vbs
├── LICENSE
└── README.md

Sources: OfficeScrubC2R.psd1:82-91

PowerShell Gallery Publication

Prerequisites

  • NuGet API Key: Obtain from PowerShell Gallery
  • Account Access: Registered PowerShell Gallery account with ownership
  • Module Validation: All files must pass Test-ModuleManifest

Publication Process

sequenceDiagram
    participant Dev as Developer
    participant Local as Local Machine
    participant PSGal as PowerShell Gallery
    participant Users as End Users
    
    Dev->>Local: Test-ModuleManifest
    Local-->>Dev: Validation Pass
    
    Dev->>Local: Publish-Module with API Key
    Local->>PSGal: Upload Module Package
    
    PSGal->>PSGal: Validate Package
    PSGal->>PSGal: Scan for Security Issues
    PSGal->>PSGal: Extract Metadata
    
    PSGal-->>Local: Publish Success
    Local-->>Dev: Confirmation
    
    Note over PSGal: Module Available (5-10 min delay)
    
    Users->>PSGal: Install-Module OfficeScrubC2R
    PSGal-->>Users: Download and Install
Loading

Publication Commands

# Step 1: Final validation
$manifest = Test-ModuleManifest -Path .\OfficeScrubC2R.psd1
if (-not $manifest) {
    throw "Manifest validation failed"
}

Write-Host "Publishing version: $($manifest.Version)"
Write-Host "Module name: $($manifest.Name)"

# Step 2: Verify all files included
$fileList = $manifest.FileList
foreach ($file in $fileList) {
    if (-not (Test-Path $file)) {
        throw "Required file missing: $file"
    }
}

# Step 3: Publish to PowerShell Gallery
$apiKey = Read-Host -Prompt "Enter NuGet API Key" -AsSecureString
$apiKeyPlain = [System.Runtime.InteropServices.Marshal]::PtrToStringAuto(
    [System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($apiKey)
)

Publish-Module -Path . -NuGetApiKey $apiKeyPlain -Verbose -WhatIf

# Step 4: After verifying WhatIf output, publish for real
Publish-Module -Path . -NuGetApiKey $apiKeyPlain -Verbose

Important Considerations:

  • Publication is irreversible - versions cannot be deleted, only unlisted
  • Module must increment version number for each publish
  • PowerShell Gallery caches metadata (5-10 minute propagation delay)
  • Zone.Identifier streams cause publication failure

Sources: CONTRIBUTING.md:203-211, .github/workflows/ci.yml:101-108

Post-Release Verification

Verify PowerShell Gallery Installation

# Wait 5-10 minutes after publication for propagation

# Search for module
Find-Module -Name OfficeScrubC2R -Repository PSGallery

# Install from Gallery
Install-Module -Name OfficeScrubC2R -Scope CurrentUser -Force

# Verify version
Get-Module -Name OfficeScrubC2R -ListAvailable | Select-Object Name, Version

# Test import
Import-Module OfficeScrubC2R -Force
Get-Command -Module OfficeScrubC2R

Verification Checklist

Item Command Expected Result
Module findable Find-Module OfficeScrubC2R Returns module info
Version correct (Find-Module OfficeScrubC2R).Version Matches release version
Installation works Install-Module OfficeScrubC2R No errors
Import succeeds Import-Module OfficeScrubC2R No errors
Functions exported Get-Command -Module OfficeScrubC2R Returns 5 functions
Native DLL loads Import-OfficeScrubNative Returns $true
Help available Get-Help New-OfficeScrubOrchestrator Shows help content

GitHub Release Verification

  • Release appears at https://github.com/Calvindd2f/OfficeScrubC2R/releases
  • Release notes rendered correctly
  • Tag linked to correct commit
  • Download counts incrementing
  • Assets downloadable

Sources: OfficeScrubC2R.psd1:58-64

Rollback Procedures

If CI Fails After Tagging

# Delete remote tag
git push --delete origin v3.1.0

# Delete local tag
git tag -d v3.1.0

# Fix issues
# ... make corrections ...

# Re-tag with same version after fixes
git tag -a v3.1.0 -m "Release v3.1.0"
git push --tags

If PowerShell Gallery Publish Fails

PowerShell Gallery publications cannot be deleted, but can be unlisted:

# Unlist problematic version (requires web portal)
# Navigate to: https://www.powershellgallery.com/packages/OfficeScrubC2R/manage
# Click "Unlist" for the problematic version

Important: Unlisted versions remain downloadable by direct version specification but won't appear in search results. The next publish must use a higher version number.

If Major Issues Discovered Post-Release

  1. Immediately unlist the version on PowerShell Gallery
  2. Create GitHub issue documenting the problem
  3. Add warning to GitHub Release description
  4. Prepare hotfix with incremented PATCH version
  5. Follow release process for hotfix
  6. Update CHANGELOG with retroactive notes

Release Artifacts and Distribution

Distribution Channels

Channel URL Purpose
PowerShell Gallery https://www.powershellgallery.com/packages/OfficeScrubC2R Primary distribution
GitHub Releases https://github.com/Calvindd2f/OfficeScrubC2R/releases Manual downloads
Repository https://github.com/Calvindd2f/OfficeScrubC2R Source code access

Package Contents

PowerShell Gallery Package (automatically generated from OfficeScrubC2R.psd1:82-91):

  • OfficeScrubC2R.psd1 - Module manifest
  • OfficeScrubC2R.psm1 - PowerShell module
  • OfficeScrubNative.dll - Native performance library
  • OfficeScrubC2R-Native.cs - Native source (reference)
  • direct_conversion.cs - Direct conversion source (reference)
  • docs/source/OfficeScrubC2R.vbs - Original VBScript (reference)
  • LICENSE - MIT license
  • README.md - Documentation

GitHub Release Artifacts (manually attached):

  • Same as PowerShell Gallery package, bundled as .zip
  • Optional: Platform-specific builds if multi-targeting

Version Compatibility Matrix

OfficeScrubC2R Version PowerShell Version .NET Framework Office Versions Supported
3.x 5.1, 7+ 4.5+ 2013, 2016, 2019, 365
2.19.x 5.1, 7+ 4.5+ 2013, 2016, 2019, 365
2.2.x 5.1+ 4.5+ 2013, 2016, 2019, 365

Sources: OfficeScrubC2R.psd1:9, OfficeScrubC2R.psd1:29, OfficeScrubC2R.psd1:32, CHANGELOG.md:144-148

Release Cadence and Planning

Release Types

Major Releases (X.0.0):

  • Frequency: As needed for breaking changes
  • Planning: Documented in GitHub issues/milestones
  • Communication: Advance notice in README and release notes

Minor Releases (X.Y.0):

  • Frequency: Monthly or feature-complete
  • Planning: Feature requests and enhancements
  • Communication: Regular update cycle

Patch Releases (X.Y.Z):

  • Frequency: As needed for critical bugs
  • Planning: Immediate response to reported issues
  • Communication: Quick turnaround with focused fixes

Release Timeline Example

gantt
    title Release Cycle Example
    dateFormat YYYY-MM-DD
    
    section Development
    Feature work           :dev1, 2025-01-01, 14d
    Code review           :dev2, after dev1, 3d
    Testing               :dev3, after dev2, 3d
    
    section Release Prep
    Update version        :rel1, after dev3, 1d
    Update CHANGELOG      :rel2, after rel1, 1d
    Build and test        :rel3, after rel2, 1d
    
    section Publication
    Create tag            :pub1, after rel3, 1d
    CI validation         :pub2, after pub1, 1d
    GitHub release        :pub3, after pub2, 1d
    PSGallery publish     :pub4, after pub3, 1d
    
    section Verification
    Verify installation   :ver1, after pub4, 1d
    Monitor issues        :ver2, after ver1, 7d
Loading

Sources: CONTRIBUTING.md:184-200

Troubleshooting Release Issues

Common Problems and Solutions

Problem Cause Solution
Test-ModuleManifest fails Invalid manifest syntax Validate PowerShell syntax in .psd1
CI build fails Missing dependencies Ensure build.ps1 runs locally first
PSGallery rejects package Zone.Identifier present Run Get-ChildItem -Recurse | Unblock-File
Module not findable Propagation delay Wait 10 minutes after publish
DLL load fails Architecture mismatch Verify compilation targets in build.ps1
Version conflict Version already published Increment version number

Diagnostic Commands

# Check manifest validity
Test-ModuleManifest -Path .\OfficeScrubC2R.psd1 -ErrorAction Stop

# Check for blocked files
Get-ChildItem -Recurse -File | Where-Object {
    Get-Item $_.FullName -Stream Zone.Identifier -ErrorAction SilentlyContinue
}

# Verify DLL architecture
[System.Reflection.Assembly]::LoadFile(
    (Resolve-Path .\OfficeScrubNative.dll).Path
).GetName().ProcessorArchitecture

# Check PowerShell Gallery status
Find-Module -Name OfficeScrubC2R -AllVersions | Format-Table Version, PublishedDate

Sources: .github/workflows/ci.yml:76-108

Document Version: 1.0
Last Updated: 2025-01-15
Maintained By: OfficeScrubC2R Maintainers

Clone this wiki locally