View source for Puppet/New module

'''These docs are outdated, but kept here for historical reasons and search access. To view the latest docs, please refer to http://docs.openstack.org/developer/puppet-openstack-guide/'''

<strike>
== Starting a new module ==

=== On the community side ===

Community wise, one should respect the following process to submit a new module

* Send a message to the mailing-list annoucing one's will to create a new puppet module for openstack, and wait for the thread to take place.
* Once a consensus is agreed upon on the mailing list the user can proceed further by doing two actions:

# Submit a review to openstack-infra/project-config to create the project (Add PTL and some core as reviewers)
# Submit a review to openstack/governance to state that the project is part of PuppetOpenstack (Add PTL and some core as reviewers)


For the governance addition please follow the process explained here:  http://docs.openstack.org/infra/manual/creators.html#add-new-repository-to-the-governance-repository

=== On the technical side ===

The community has developed two projects related to modules file management:
    
* puppet-openstack-cookiecutter (https://github.com/openstack/puppet-openstack-cookiecutter) : This project aims to help bootstrap a new puppet module that will be compliant with the community expectations (organization, naming, etc...). It takes user inputs and a project template and generate the skeleton of the modules.
* puppet-modulesync-configs (https://github.com/openstack/puppet-modulesync-configs) : This project aims to gather in a single repository the files that are common and need to be kept in sync across all openstack/puppet-* modules.


Why two projects? While modulesync makes it easy to keep a set of common file synced between projects (Gemfile, Rakefile, nodesets,...), it is not intented for dynamic content and path (class name, provider, etc...), hence the use of cookiecutter and the existence of both projects.


Modulesync: https://github.com/openstack/puppet-modulesync-configs

Cookiecutter: https://github.com/openstack/puppet-openstack-cookiecutter

=== In practice ===

Requirements :
* cookiecutter
* modulesync (>= 0.5.0)
* git
* git-review
* digest


To make the boilerplating of a new Puppet module easier a script is provided. https://github.com/openstack/puppet-openstack-cookiecutter/blob/master/contrib/bootstrap.sh

What is does is the following

'''Step 1: Generate the skeleton of the module'''

It uses cookiecutter to generate the skeleton of the module.

'''Step 2: Retrieve the git repository of the project'''

It retrieves the official openstack repository of your project

'''Step 3: Create the initial commit with the file present in the skeleton'''

Reuse the .git from the openstack repository and make an initial commit of the file present in the skeleton directory

'''Step 4: Retrieve the puppet-modulesync-configs directory and configure it for your need'''

It clones the puppet-modulesync-configs directory and configure modulesync.yml and managed_modules.yml accordingly

'''Step 5: Run msync and amend the initial commit'''

It runs modulesync in noop mode and amend the commit from Step 3 with the files from puppet-modulesync-configs

At this point you should have generated a minimalist but functional module.

There are some things that cannot be automated and are marked via the FIXME tag.
The impacted files are :
* manifests/keystone/auth.pp
* spec/classes/MYMODULENAME_keystone_auth_spec.rb
* README.md

 
Now one only have to run git review in the folder indicated in the output of the script
</strike>