From 2bb7b2efec72043c67da3d2d5f70c02d248abeea Mon Sep 17 00:00:00 2001 From: James Elliott Date: Fri, 30 Jul 2021 14:17:44 +1000 Subject: [PATCH] docs: update style guidelines (#2172) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update the style guidelines. Co-authored-by: Clément Michaud --- docs/contributing/style-guide.md | 59 +++++++++++++++++++++++++++++++- 1 file changed, 58 insertions(+), 1 deletion(-) diff --git a/docs/contributing/style-guide.md b/docs/contributing/style-guide.md index b531e589..5d2af883 100644 --- a/docs/contributing/style-guide.md +++ b/docs/contributing/style-guide.md @@ -41,4 +41,61 @@ This includes but is not limited to the following file types: - YAML (*.yml, *.yaml) - Markdown (*.md) - JavaScript (*.js) -- TypeScript (*.ts, *.tsx) \ No newline at end of file +- TypeScript (*.ts, *.tsx) + +### Error Strings + +Error messages should follow the standard go format. This format can be found in the [golang code review comments](https://github.com/golang/go/wiki/CodeReviewComments#error-strings) +however the key points are: + +- errors should not start with capital letters (excluding proper nouns, acronyms, or initialism) +- errors should not end with punctuation +- these restrictions do not apply to logging, only the error type itself + +### Configuration Documentation + +The configuration documentation has a consistent format this section describes it as best as possible. It's recommended +to check additional sections for examples. + +#### Layout + +The first thing in the configuration documentation should be a description of the area. This is promptly followed by the +configuration heading (h2 / indent 2) which has an example full configuration. + +Under the configuration example each option in the configuration needs to be documented with its own heading +(h3 / indent 3). Immediately following the heading is a div with some stylized icons. + +The body of the section is to contain paragraphs describing the usage and information specific to that value. + + +**Example Stylized Icons:** + +```html +
+type: string +{: .label .label-config .label-purple } +default: example +{: .label .label-config .label-blue } +required: no +{: .label .label-config .label-green } +
+``` + +##### type + +This section has the type of the value in a semi human readable format. Some example values are `string`, `integer`, +`boolean`, `list(string)`, `duration`. This is immediately followed by the styles `.label`, `.label-config`, +`.label-purple`. + +##### default + +This section has the default of the value if one exists, this section can be completely omitted if there is no default. +This is immediately followed by the styles `.label`, `.label-config`, +`.label-blue`. + +##### required + +This section has the required status of the value and must be one of `yes`, `no`, or `situational`. Situational means it +depends on other configuration options. If it's situational the situational usage should be documented. This is +immediately followed by the styles `.label`, `.label-config`, and a traffic lights color label, i.e. if yes `.label-red`, +if no `.label-green`, or if situational `.label-yellow`.