Updating the Module Metadata

First, review and update the Chapter 16. In particular, make sure that the following files have been created, and are up to date:

• README.md, as described in “Writing a Good README”
• CHANGELOG.md, as described in “Maintaining the Change Log”
• metadata.json, as described in “Updating Module Metadata”
• LICENSE, as described in “Identifying the License”

Every one of these files is used by the Puppet Forge to create details for users of your module.

One feature of the metadata we didn’t discuss previously was keyword tags. These are used by the Puppet Forge search engine to help users find your module.

Update the metadata.json file to include an array of keyword tags relevant to your project. Tags cannot contain spaces, and should not match any valid value from $facts['operatingsystem'].

  "tags": [ "agent", "server" ],

Packaging a Module

After verifying the metadata is accurate, use puppet module build to package the module.

$ puppet module build
Notice: Building jorhett-puppet for release
Module built: jorhett-puppet/pkg/jorhett-puppet-1.2.1.tar.gz

Note that the pkg/ directory can become very full over time. You may want to clean that out. I recommend adding this directory to your .gitignore file.

Uploading a Module to the Puppet Forge

There is no API for uploading modules to the Puppet Forge. Using a web browser, follow this process to add or update a module you own:

1. Navigate to Puppet Forge.
2. Click Login or Sign Up if necessary.
3. Click Publish in the upper-right corner beside your name (see Figure 18-1).
4. Click Choose File and select the module package you created in the previous step.
5. Click Upload.

Figure 18-1. You’ll find a link to Publish modules near your name on the top right

Your module will be added to the Forge. The README and CHANGELOG from your module will be shown as the web page for your module. The results of standard tests and community feedback will be added to the page when they are available.

If this process has changed since this book was published, the revised process should be documented at “Publishing Modules on the Puppet Forge”.

Publishing a Module on GitHub

It is common and expected for you to have a place to accept bug reports and pull requests for your module. GitHub is by far the most common location for this. The following steps will create a GitHub repository for your module.

If you haven’t installed Git already, do that now:

[vagrant@client ~]$ sudo yum install -y git
...snip...
Installed:
  git.x86_64 0:1.8.3.1-4.el7                                                                                                                                                                                  

Dependency Installed:
  libgnome-keyring.x86_64 0:3.8.0-3.el7  perl-Error.noarch 1:0.17020-2.el7
  perl-Git.noarch 0:1.8.3.1-4.el7        perl-TermReadKey.x86_64 0:2.30-20.el7
  rsync.x86_64 0:3.0.9-15.el7       

Complete!

Configure the Git software with your name and email address:

$ git config --global user.name "Jane Doe"
$ git config --global user.email [email protected]

If you don’t already have a GitHub account, create one at https://github.com/join.

Create a new repository in your GitHub account at https://github.com/new. You will likely want to name the repository by replacing your name in the module with puppet-, as GitHub already organizes the repository under your name. Ignore the options below the name and click Create Repository.

Set up version tracking of your module by running the following command within your module directory:

$ git init
Initialized empty Git repository in
    /home/vagrant/.puppet/modules/jorhett-puppet/.git/

There are some files to avoid uploading to the source repository. These include:

• Binary packages of the module
• Dependency fixtures created by rspec for testing

To prevent this, create a .gitignore file with the following contents:

# .gitignore
/pkg/
/spec/fixtures/

Commit your module to the Git repository by running the following commands within your module directory:

$ git add --all

$ git commit -m "Initial commit"
[master (root-commit) e804295] initial commit
11 files changed, 197 insertions(+), 0 deletions(-)
 create mode 100644 Gemfile
 create mode 100644 README.md
 create mode 100644 CHANGELOG.md
 create mode 100644 Rakefile
 create mode 100644 manifests/init.pp
 create mode 100644 manifests/client.pp
 create mode 100644 manifests/master.pp
 create mode 100644 metadata.json
 create mode 100644 spec/classes/init_spec.rb
 create mode 100644 spec/spec_helper.rb
 create mode 100644 tests/init.pp

You have now committed your changes to the source tree. However, they are not yet pushed up to GitHub. Let’s configure GitHub as our remote origin. If you have a different origin and are just pushing to GitHub as a remote branch, we expect that you know how to do that.

$ git remote add origin https://github.com/janedoe/modulename.git
$ git push -u origin master
Counting objects: 14, done.
Compressing objects: 100% (11/11), done.
Writing objects: 100% (14/14), 3.68 KiB | 0 bytes/s, done.
Total 14 (delta 0), reused 0 (delta 0)
To https://github.com/jorhett/puppet-systemstd.git
 * [new branch]      master -> master
Branch master set up to track remote branch master from origin.

Whenever you wish to publish a change to the module, make sure to update the version number and changes for the version in the following files:

• metadata.json
• README.md
• CHANGELOG.md

Commit these changes to the repository, and then push them up to GitHub.

$ git commit -a -m "Updated documentation for version X.Y"
[master a4cc6b7] Updated documentation
 Committer: jorhett [email protected]
 3 files changed, 11 insertions(+), 2 deletions(-)
$ git push
Counting objects: 14, done.
Compressing objects: 100% (11/11), done.
...

Automating Module Publishing

There is a community-provided Ruby gem that automates the task of updating your module on the Forge. You can find documentation for this at maestrodev/puppet-blacksmith on GitHub.

Preparation for using this gem requires adding two lines to Rakefile, and placing your Puppet Forge credentials in a text file in your home directory.

If you’ve just made a minor fix to your module, the release process could be as simple as this:

$ rake module:bump:patch
$ $EDITOR CHANGELOG.md
$ rake module:tag
$ rake module:push

You can also use module:bump:minor after adding new features, or module:bump:major after making changes that are not backward-compatible.

Getting Approved Status from Puppet Labs

At the time this book was written, the approval requirements were as follows:

• Solve a unique problem well. Puppet Labs won’t approve multiple modules that solve the same problem.
• Comply with the Puppet Style Guide. No warnings can be issued by syntax checking tools like puppet-lint.
• Have regular updates from more than one person or organization. Have Forge updates in the last six months, and less than a one-month lag between source repo (e.g., GitHub) and the Forge.
• Provide thorough and readable documentation.
• Be licensed under Apache, MIT, or BSD licenses.
• Have every standard metadata field filled out, including Puppet version and operating system compatibility.
• Be versioned according to SemVer guidelines to keep expectations consistent with regards to upgrades.
• Have rspec and acceptance tests for every manifest, and unit tests for types, providers, facts, and functions.

Given the nature of supporting a community of published modules, I feel the requirements are straightforward, easy to understand, and generally easy to apply.

You can check for updates to the approval guidelines at https://forge.puppetlabs.com/approved/criteria.

To have your module marked as Puppet Approved, open an issue in the Forge Modules project at https://tickets.puppetlabs.com/. Request that the module be evaluated for Approved status.