12
edits
ReleaseEngineering/PuppetAgain/HowTo/Hack on PuppetAgain: Difference between revisions
Jump to navigation
Jump to search
ReleaseEngineering/PuppetAgain/HowTo/Hack on PuppetAgain (view source)
Revision as of 12:24, 7 July 2017
, 7 July 2017no edit summary
(→Exceptions to Review Requirement: Missing condition for self review) |
No edit summary |
||
| Line 14: | Line 14: | ||
* <tt>a=userdir</tt> - self-approval if you're changing your '''*own*''' user directory files with the explicit rule of excluding large files | * <tt>a=userdir</tt> - self-approval if you're changing your '''*own*''' user directory files with the explicit rule of excluding large files | ||
* <tt>r=bustage</tt> - self-approval if you're backing out a broken update, in order to restore service. | * <tt>r=bustage</tt> - self-approval if you're backing out a broken update, in order to restore service. | ||
= Coding guidelines = | |||
== Classes == | |||
Class name should not contain "-". | |||
== Spacing, indentation, and whitespace == | |||
Module manifests should follow best practices for spacing, indentation, and whitespace. | |||
Manifests: | |||
* Must use two-space soft tabs, | |||
* Must not use literal tab characters, | |||
* Must not contain trailing whitespace, | |||
* Must include trailing commas after all resource attributes and parameter definitions, | |||
* Must end the last line with a new line, | |||
* Must use one space between the resource type and opening brace, one space between the opening brace and the title, and no spaces between the title and colon. | |||
== Arrays and hashes == | |||
To increase readability of arrays and hashes, it is almost always beneficial to break up the elements on separate lines. | |||
Use a single line only if that results in overall better readability of the construct where it appears, such as when it is very short. When breaking arrays and hashes, they should have: | |||
* Each element on its on line, | |||
* Each new element line indented one level, | |||
* First and last lines used only for the syntax of that data type. | |||
== Documentation comments == | |||
Documentation comments for Puppet Strings should be included for each of your classes, defined types, functions, and resource types and providers. | |||
See the [https://docs.puppet.com/puppet/5.0/style_guide.html#documenting-puppet-code documentation section] of this guide for complete documentation recommendations | |||
== Arrow alignment == | |||
Hash rockets (=>) in a resource’s attribute/value list may be aligned. The hash rockets should be placed one space ahead of the longest attribute name. Nested blocks must be indented by two spaces, and hash rockets within a nested block may be aligned (one space ahead of the longest attribute name). | |||
Each attribute should be placed on a separate line, with the exception that very short or single purpose resource declarations may be declared on a single line. | |||
== Attribute ordering == | |||
If a resource declaration includes an ensure attribute, it should be the first attribute specified so that a user can quickly see if the resource is being created or deleted. | |||
== File modes == | |||
* POSIX numeric notation must be represented as 4 digits. | |||
* POSIX symbolic notation must be a string. | |||
* You should not use file mode with Windows; instead use the acl module. | |||
* You should use numeric notation whenever possible. | |||
* The file mode attribute should always be a quoted string, never an integer. | |||
== Resource attribute indentation and alignment == | |||
Resource attributes must be uniformly indented in two spaces from the title. | |||
== Display order of parameters == | |||
In parameterized class and defined type declarations, required parameters must be listed before optional parameters (that is, parameters with defaults). Required parameters are parameters which are not set to anything, including undef. For example, parameters such as passwords or IP addresses might not have reasonable default values. | |||
Note that treating a parameter like a namevar and defaulting it to $title or $name does not make it a required parameter. It should still be listed following the order recommended here. | |||
== Parameter indentation and alignment == | |||
Parameters to classes or defined types must be uniformly indented in two spaces from the title. The equals sign should be aligned. | |||
== Variable format == | |||
When defining variables you must only use numbers, lowercase letters, and underscores. '''Do not use uppercased letters within a word''', such as “CamelCase”, as it introduces inconsistency in style. You must not use dashes, as they are not syntactically valid. | |||
== Defaults for case statements and selectors == | |||
Case statements must have default cases. If you want the default case to be “do nothing,” you must include it as an explicit default: {} for clarity’s sake. | |||
Case and selector values must be quoted. Selectors should omit default selections only if you explicitly want catalog compilation to fail when no value matches. | |||
== Documenting Puppet code == | |||
Use Puppet Strings code comments to document your Puppet classes, defined types, functions, and resource types and providers. Strings processes the README and comments from your code into HTML or JSON format documentation. This allows you and your users to generate detailed documentation for your module. | |||
Include comments for each element (classes, functions, defined types, parameters, and so on) in your module. If used, comments must precede the code for that element. Comments should contain the following information, arranged in this order: | |||
* A description giving an overview of what the element does. | |||
* Any additional information about valid values that is not clear from the data type. (For example, if the data type is [String], but the value must specifically be a path.) | |||
* The default value, if any for that element. | |||
Multiline descriptions must be uniformly indented by at least one space. | |||
For more coding guidelines, please visit [https://docs.puppet.com/puppet/5.0/style_guide.html puppet style guide] page | |||
= Patch Guidelines / Review Checklist = | = Patch Guidelines / Review Checklist = | ||