Skip to content

Instantly share code, notes, and snippets.

@lukebakken

lukebakken/MIGRATION_TO_COMMUNITY.md

Last active January 2, 2026 18:47
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save lukebakken/935997613707af0853fab391fbd2d41d to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save lukebakken/935997613707af0853fab391fbd2d41d to your computer and use it in GitHub Desktop.
Download ZIP
au-packages-template
Raw
MIGRATION_TO_COMMUNITY.md

Migration to chocolatey-community Organization

Overview

This document outlines the steps required if the chocolatey-community organization chooses to accept this template and its associated wiki as the official AU packages template.

Current State

Repositories:

  • Template: chocolatey-beam/au-packages-template
  • Wiki: chocolatey-beam/au-packages-template.wiki

Target:

  • Template: chocolatey-community/au-packages-template
  • Wiki: chocolatey-community/au-packages-template.wiki

Migration Checklist

1. Repository Transfer

  • Transfer chocolatey-beam/au-packages-template to chocolatey-community organization
  • Verify all branches transferred correctly
  • Verify all tags transferred correctly
  • Verify GitHub Actions workflows are enabled

2. Wiki Migration

The wiki is a separate git repository that must be migrated independently:

# Clone the current wiki
git clone https://github.com/chocolatey-beam/au-packages-template.wiki.git

# Add new remote for chocolatey-community
cd au-packages-template.wiki
git remote add community https://github.com/chocolatey-community/au-packages-template.wiki.git

# Push all content to new location
git push community master

# Verify wiki content appears at new location

3. Update Repository References

After transfer, update all references in the template:

Files to update:

  • README.md - Update wiki links from chocolatey-beam to chocolatey-community
  • .appveyor.yml - Update github_user_repo placeholder
  • update_all.ps1 - Update template URL comment
  • update_vars_default.ps1 - Update template URL comment
  • cinst-gh.ps1 - Update example repository URL

Search and replace:

# Find all references to chocolatey-beam
grep -r "chocolatey-beam" . --exclude-dir=.git

# Replace with chocolatey-community
# (Do this carefully, file by file)

4. GitHub Settings Configuration

Branches:

  • Set master as default branch
  • Enable branch protection for master:
    • Require pull request reviews
    • Require status checks (validate workflow)
    • Require branches to be up to date

Secrets:

  • Document required secrets for workflows:
    • API_KEY - GitHub API token for gist updates
    • CHOCOLATEY_API_KEY - Chocolatey API key for package pushes
  • Note: These are placeholders in template, users configure after forking

Actions:

  • Verify GitHub Actions are enabled
  • Verify workflows can be manually triggered
  • Test validate workflow runs on PR

5. Documentation Updates

README.md:

  • Update "Fork this project" section to reference chocolatey-community/au-packages-template
  • Update all wiki links to point to chocolatey-community organization
  • Update example repository URLs

Wiki:

  • Update all code examples with correct organization name
  • Update installation instructions
  • Update troubleshooting guides
  • Verify all internal wiki links work

6. Deprecation of Old Template

After migration is complete:

  • Archive majkinetor/au-packages-template (if not already archived)
  • Add deprecation notice to old template README
  • Redirect users to chocolatey-community/au-packages-template
  • Update AU module documentation to reference new template

7. Announcement and Communication

  • Announce new template location in chocolatey-community discussions
  • Update AU module README to link to new template
  • Update Chocolatey documentation if it references the old template
  • Notify community via Discord/Gitter

Testing After Migration

Before announcing, verify everything works:

  1. Fork the migrated template to a test account
  2. Follow the setup instructions in README
  3. Configure secrets for testing
  4. Run validate workflow - Should pass
  5. Manually trigger update workflow - Should run without errors
  6. Test AppVeyor integration - Should work as before
  7. Verify wiki links - All links should work

Rollback Plan

If issues are discovered after migration:

  1. Keep chocolatey-beam version available as backup
  2. Document any issues found
  3. Fix in chocolatey-community version
  4. Re-test thoroughly
  5. Only deprecate chocolatey-beam version after stable period

Timeline Estimate

  • Repository transfer: 1 hour
  • Wiki migration: 1 hour
  • Reference updates: 2 hours
  • Testing: 2 hours
  • Documentation: 1 hour
  • Total: ~7 hours

Contact

Current Maintainer: Luke Bakken (luke@bakken.io)

For Migration Questions:

  • Open issue in chocolatey-beam/au-packages-template
  • Contact chocolatey-community maintainers
  • Discuss in chocolatey-community Discord

Post-Migration Maintenance

After migration, the chocolatey-community organization will be responsible for:

  • Reviewing and merging pull requests
  • Updating documentation
  • Maintaining wiki content
  • Responding to issues
  • Keeping template up-to-date with AU module changes

Document created: January 2, 2026 Status: Pre-migration planning

Raw
MODERNIZATION_SUMMARY.md

Chocolatey-AU Template Modernization - Complete Summary

Background

The Problem

While migrating the Erlang, Elixir, and rebar3 Chocolatey packages from custom update scripts to the Chocolatey-AU framework, I discovered that the widely-used majkinetor/au-packages-template repository was outdated and caused confusion:

  1. Referenced the wrong module - Template used AU (archived 2022) instead of Chocolatey-AU (current, v1.0.0+ from March 2024)
  2. PowerShell 7 incompatibility - Template didn't work with PowerShell 7 due to breaking changes in 7.3.0+
  3. No GitHub Actions support - Only AppVeyor was documented
  4. Code quality issues - Used aliases, Write-Host, inconsistent formatting
  5. Outdated documentation - Wiki referenced archived repositories and old module names

This led users (including myself) to install the wrong module version, causing compatibility issues and confusion.

My Background

I maintain several BEAM ecosystem packages for Chocolatey:

  • RabbitMQ - https://github.com/rabbitmq/chocolatey-package (official package)
  • Erlang - Took over maintenance, keeping it current with OTP releases
  • Elixir - Maintaining packages for multiple OTP versions
  • rebar3 - Erlang build tool package

The need to keep these packages updated efficiently drove the migration to Chocolatey-AU and the discovery of these template issues.

Work Completed

Phase 1: Template Repository Updates

Module Name Migration:

  • Updated all Import-Module AU to Import-Module Chocolatey-AU
  • Updated README installation instructions
  • Updated .appveyor.yml to clone from chocolatey-community fork
  • Updated all repository URLs from majkinetor to chocolatey-community

PowerShell 7 Compatibility:

  • Added $PSNativeCommandArgumentPassing = 'Legacy' workaround to Update-Packages.ps1
  • Created comprehensive POWERSHELL7.md documentation
  • Explained the breaking change and why it matters
  • Provided alternative solutions

Script Naming Conventions:

  • Renamed update_all.ps1 → Update-Packages.ps1
  • Renamed test_all.ps1 → Test-Packages.ps1
  • Created Invoke-Validation.ps1 for PSScriptAnalyzer checks
  • Updated all references throughout codebase

Code Quality Improvements:

  • Replaced all cmdlet aliases with full names (24 instances)
  • Replaced Write-Host with Write-Information (9 instances)
  • Removed trailing whitespace from all files
  • Fixed inconsistent indentation
  • Removed unused variables
  • Auto-formatted all PowerShell files

PSScriptAnalyzer Integration:

  • Created PSScriptAnalyzerSettings.psd1 with comprehensive rules
  • Added formatting rules (indentation, braces, whitespace, casing)
  • Added PowerShell 5.1/7 compatibility checking
  • Configured appropriate suppressions for AU framework requirements
  • All sample packages now pass validation

GitHub Actions Workflows:

  • Created update.yml for automatic package updates
  • Created validate.yml for code quality checks on PR/push
  • Disabled update workflow by default (template repository)
  • Added comprehensive setup instructions in README
  • Maintained compatibility with existing AppVeyor setup

Line Ending Consistency:

  • Added .gitattributes enforcing LF line endings
  • Ensures cross-platform compatibility
  • Prevents CRLF/LF conflicts

Phase 2: Wiki Updates

Module Name Updates:

  • Replaced all "AU" references with "Chocolatey-AU" (24 instances across 7 files)
  • Updated Import-Module examples
  • Renamed AU-In-Use.md to Chocolatey-AU-In-Use.md

Repository URL Updates:

  • Updated all majkinetor/au-packages-template URLs to chocolatey-beam/au-packages-template
  • Updated all majkinetor/au URLs to chocolatey-community/chocolatey-au
  • Fixed wiki internal links

Script Name Updates:

  • Updated update_all.ps1 references to Update-Packages.ps1
  • Updated test_all.ps1 references to Test-Packages.ps1
  • Updated code examples throughout

New Content:

  • Created comprehensive GitHub-Actions.md page
  • Documented setup process step-by-step
  • Explained workflows and configuration
  • Added troubleshooting section
  • Compared GitHub Actions vs AppVeyor

Formatting Improvements:

  • Converted inline TOC navigation to bullet point style
  • Removed non-ASCII characters
  • Improved readability

Phase 3: Critical Bug Discovery

PowerShell 7 Empty String Bug:

Discovered a critical bug in the Chocolatey-AU module affecting PowerShell 7 users:

The Problem: PowerShell 7.3.0+ changed how empty strings are passed to external commands. In PowerShell 5.1, empty strings were filtered out. In PowerShell 7+, they're passed as "".

The AU module's Push-Package.ps1 has:

$force_push = if ($Env:au_ForcePush) { '--force' } else { '' }
choco push $package $force_push

In PowerShell 7, the empty string becomes "" which choco interprets as a filename, causing "file not found" errors.

Why chocolatey-community Didn't Notice: The chocolatey-community/chocolatey-packages repository uses AppVeyor with PowerShell 5.1, which has the old behavior. They never encountered the bug.

The Fix: Submitted PR #85 changing '' to $null, which is filtered in both PowerShell versions.

Detailed Analysis: https://gist.github.com/lukebakken/e7f9ba1fe1c71a46222ddac4b26f9d06

Testing Performed

Template Repository:

  • ✅ All PSScriptAnalyzer checks pass
  • ✅ Sample package (copyq) updates successfully
  • ✅ Validation workflow works
  • ✅ PowerShell 5.1 compatibility verified
  • ✅ PowerShell 7 compatibility verified

Real-World Usage:

  • ✅ Migrated rebar3 package to AU framework
  • ✅ Created automated Elixir package system (4 packages for OTP 26/27/28)
  • ✅ Packages successfully pushed to Chocolatey
  • ✅ GitHub Actions workflows running in production

Benefits to Community

For New Users:

  • Clear, up-to-date instructions
  • Works with modern PowerShell 7
  • Choice of AppVeyor or GitHub Actions
  • Better code quality from the start

For Existing Users:

  • Migration path from old template
  • PowerShell 7 compatibility guidance
  • GitHub Actions alternative to AppVeyor
  • Best practices and validation tools

For Maintainers:

  • Reduced support burden (clearer docs)
  • Modern CI/CD examples
  • Compatibility with current tools
  • Active maintenance commitment

Migration to chocolatey-community

I've prepared a complete migration guide: https://gist.github.com/lukebakken/935997613707af0853fab391fbd2d41d

What needs to happen:

  1. Transfer repository to chocolatey-community organization
  2. Migrate wiki content (separate git repository)
  3. Update remaining references from chocolatey-beam to chocolatey-community
  4. Configure branch protection and settings
  5. Test everything works in new location
  6. Deprecate old majkinetor template with redirect

Estimated effort: ~7 hours total

Timeline: Can be done whenever chocolatey-community is ready

Ongoing Maintenance

I'm committed to maintaining this template going forward:

  • Keeping it synchronized with Chocolatey-AU updates
  • Responding to issues and pull requests
  • Updating documentation as needed
  • Testing with real-world package updates

I'm also happy to continue contributing to the Chocolatey-AU module itself, including the PowerShell 7 fix and any other improvements.

Repository Links

Current locations:

Related work:

Technical Details

For those interested in the technical specifics:

PowerShell 7 Breaking Change:

  • Introduced in PowerShell 7.3.0
  • Empty strings now passed as "" to external commands
  • Affects any code using empty strings as optional parameters
  • Workaround: $PSNativeCommandArgumentPassing = 'Legacy'
  • Proper fix: Use $null instead of ''

Compatibility Testing:

  • PSScriptAnalyzer rules check PowerShell 5.1, 7.0, and 7.4
  • Validates syntax, commands, and types across versions
  • Catches issues before they reach users

Code Quality:

  • Consistent formatting enforced
  • No aliases in scripts
  • Proper error handling
  • Clean, maintainable code

Questions and Feedback

I welcome any feedback on:

  • The changes and approach taken
  • The migration proposal
  • Additional improvements needed
  • How to best integrate with chocolatey-community

Thank you for your time and for maintaining the Chocolatey-AU project!

Contact: Luke Bakken (luke@bakken.io) Chocolatey Profile: https://community.chocolatey.org/profiles/lukebakken

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment