transfer_to_community.md

transfer_to_community.md

Advice for migrating existing [Forge] modules to Puppet-Community

Basics

Transferring a module to another owner is pretty simple when you break it down. See puppetlabs-nginx for an example.

Basically, you want to avoid surprising existing users of your module by raising a number of signals that will get their notice. It's as easy as 1-2-3!

1. Transfer the GitHub repository to the puppet-community organization
2. Prepare and release the "warning" Forge release to the existing namespace
3. Publish the first "normal" Forge release to the puppet namespace

Step 1

If you're using GitHub, this step is simple. Simply read and follow this guide on how to do it, coordinating with an owner of puppet-community to handle the transfer.

Step 2

This step is the most critical. Because the Puppet Forge does not provide the same transfer capabilities as GitHub, you are responsible for signaling the transfer to your users.

Your two main tools are the version number and the README.

The pattern established by puppetlabs-nginx is three-fold. a) Increment the version to something dramatic, like 99.99.99. b) Replace the contents of your README with a warning about the transfer, including where to find the new module (link to forge.puppetlabs.com/puppet/yourmodule). c) Leave the content of your module (manifests/extensions/etc) unchanged so that mindless upgrades from the previous version to 99.99.99 causes least harm.

Step 3

<placeholder for nibalizer's description of Forge publishing>

Do you think it would be useful to also add a notify {"This puppetlabs-foobar module has changed ownership, please consider using puppet/foobar instead" loglevel => warning}

I like the notify resource in theory but it creates a changed resource event every Puppet run. So, if you upgrade but need some time to plan a migration to puppet/foobar, your reports for that time period are hosed. The notice() function is a better choice if we want to drop a note, though it only logs to the master.