Puppet Documentation

1. Just be clear about the cases where it won’t apply (ie. templates and files from other modules) … although this is rare and probably a bad form on its own.

That was a +1 to be clear – can’t modify my comment for whatever reason :–).

My problem with $module_name is that there’s a lot of magic behind it — it’s not intuitive what it will do.

Take this scenario for example:

class test {

        file { '/tmp/file':
          ensure => present,
          source => "puppet:///modules/${module_name}/file",
        }

}

class testtwo inherits test {

        File ['/tmp/file'] {
          mode +> '0600'
        }

}

In this scenario, the file comes from test/files/file.. but how about this?

class test {

        file { '/tmp/file':
          ensure => present,
          source => "puppet:///modules/${module_name}/file",
        }

}

class testtwo inherits test {

        File ['/tmp/file'] {
          mode     +> '0600',
          source   => undef,
          content  => template("${module_name}/file.erb"),
        }

}

Now the template comes from testtwo/templates/file. Why? It came from the test module the last time we referenced the resource. This behavior is magical, inconsistent and impossible to know unless you just know.

At the very least, before we promote something like this in the style guide, the variable’s behavior should be thoroughly documented and referenced to in the guide.

It does do strange things if you go against the style guide’s position on inheritance, which your example does.

http://docs.puppetlabs.com/guides/style_guide.html#class-inheritance

If you follow these recommendations then you can remove data from the module, which allows for greater portability.

Garrett Honeycutt wrote:

It does do strange things if you go against the style guide’s position on inheritance, which your example does.

http://docs.puppetlabs.com/guides/style_guide.html#class-inheritance

If you follow these recommendations then you can remove data from the module, which allows for greater portability.

Garrett, I’m not suggesting my example is a common or even best practice. What if the reader only remembers the $module_path recommendation from the style guide but not the inheritance parts? It’s a guide…

My point is that the style guide should never lead a customer down a path of potential confusion and frustration. $module_path currently does that.

What is we recommend $module_name with the caveat that you also need to adhere to not using inheritance between unrelated classes and note the style guide section?

Garrett Honeycutt wrote:

What is we recommend $module_name with the caveat that you also need to adhere to not using inheritance between unrelated classes and note the style guide section?

That’s closer to making me happy. Ideally, $module_name and other special variables should be a dedicated chunk of documentation at docs.puppetlabs.com which would clearly explain behavior, examples for use and caveats (like quirks with inheritance).

I guess I have the view that the style guide should be a place of best practices that people can adopt to improve their experience but (normally) can’t get into any more trouble by using them. To my knowledge, there’s no way for the user to understand how the variable works, thus our recommendation in the style guide would come with assumptions on its use. That’s not great.

Created #11730 to track this documentation request. Thank you for pointing it out.

With out anyone giving me a more concrete example of why this is good I am inclined to at the very most put this into the style guid as a recommended rule. Without further example of a real world use case the best I am coming up with is giving the user a very fast way to rename a module. Rename a module and every $module_name use is updated too. Sure much better than going to every resource you used it in and fixing it to match the new module’s name…but how often do you actually change a module’s name?

Also, before putting it in I would want more documentation about its behavior. The only mention on our docs site is here http://docs.puppetlabs.com/guides/faq.html

Agreed that #11730 should be done first.

Cody, you hit it. This is a very minor change that furthers our efforts of decoupling data from modules. This is indeed an edge case in usability.

Garrett Honeycutt wrote:

Created #11730 to track this documentation request. Thank you for pointing it out.

Thank YOU for creating the ticket. I do generally agree with the spirit of this ticket if that wasn’t clear before. I just objected to it without documentation, which #11730 should resolve.