ReleaseEngineering/PuppetAgain/HowTo/Hack on PuppetAgain
Hacking
PuppetAgain is (or, at least, will be) a code module, and as such people working on PuppetAgain follow the usual Mozilla process for making changes:
- hack
- post a patch, request review from a module owner or peer
- repeat until r+ (and sr+ if necessary)
- commit
- monitor and handle any problems as a result of the commit
The last point is particularly important, since puppet masters automatically update to the latest commit, and start deploying that to hosts.
Patch Guidelines
PuppetAgain should be usable externally. Do not hard-code things that external users may want to adjust, and extract them from CSV so they can be overridden easily.
- SSH authorized_keys (note that known_hosts don't hurt)
- usernames (cltbld isn't universal)
- hostnames
Do not write resources that will be instantiated on every puppet run. This makes it difficult to tell if a particular puppet run has actually done anything, and will result in misleading data in the puppet dashboard. Note that the "unless" or "onlyif" parameters to Exec, while they still run an external command (and thus aren't especially efficient), can effectively prevent a command from running.
Keep code where it belongs:
- Node declarations should only set variables and include toplevel classes (this is looking forward to using an ENC).
- Toplevel classes should only include other classes, although parameterized classes are OK. Don't do anything substantial directly in a toplevel class -- make a new module and include it.
- Package classes should only install packages. These classes should be extremely formulaic, and readers should not need to look at them to figure out what they do. Conversely, nothing else should install packages.
- Include requirements near where they are needed. It never hurts to include packages::foo from several places, if foo is used in several places.
- Where possible, break out utility modules from action modules. If your action module has a long list of basic resources (file, exec, etc.), it can probably be refactored nicely.
packages
Adjust/amend the documentation on the wiki while landing the change after review.
Avoid bad habits:
- Even if all of the barfi servers are running OpenSolaris, $::operatingsystem=="Solaris" does not mean this is a barfi server. OS does not imply role. Roles are defined in node declarations, by including toplevel::* classes.
- Specify, indeed overspecify, all necessary dependencies. Use dependency graphs. Debugging dependency errors when building a new reference system from scratch is no fun.
incomplete...