|
| 1 | += Coding conventions |
| 2 | +ifdef::env-github[] |
| 3 | +:tip-caption: :bulb: |
| 4 | +:note-caption: :information_source: |
| 5 | +:important-caption: :heavy_exclamation_mark: |
| 6 | +:caution-caption: :fire: |
| 7 | +:warning-caption: :warning: |
| 8 | +endif::[] |
| 9 | +:toc: |
| 10 | + |
| 11 | +:uri-terraform-standard-module-structure: https://www.terraform.io/docs/language/modules/develop/structure.html |
| 12 | + |
| 13 | +This is a list of coding conventions you should observe when contributing code for this project. |
| 14 | + |
| 15 | +Current conventions: |
| 16 | + |
| 17 | +- module structure |
| 18 | +- adopting the right case type |
| 19 | +- good names for files and terraform objects (resources, variables, outputs) |
| 20 | +
|
| 21 | +It is not an exhaustive list and it will be updated as we go. In the mean time, your PR reviewer may suggest conventions that are not listed here. |
| 22 | + |
| 23 | +Use PR comments and the GitHub suggestion feature to agree on the final result. |
| 24 | + |
| 25 | +== Module Structure |
| 26 | + |
| 27 | +- We adhere to the {uri-terraform-standard-module-structure}[Terraform Standard Module Structure] |
| 28 | +- Any nested module calls should be in the main file: `main.tf` is the primary entrypoint of the module |
| 29 | +- All variables and ouputs declarations should be in `variables.tf` and `outputs.tf` |
| 30 | +- All variables and outputs should have descriptions |
| 31 | +- Nested modules should exist under the `modules/` folder |
| 32 | +- Examples of using the module should exist under the `examples/` folder and have a README to explain the goal and usage of the example |
| 33 | + |
| 34 | +== Documentation format |
| 35 | + |
| 36 | +We use https://asciidoc.org/[AsciiDoc] with the `*.adoc` file extension. The only exception is for the README files that need to be displayed on the Terraform Registry: as the Terraform Registry does not support AsciiDoc, the `README` and certain other documentation must be available in Markdown format. |
| 37 | + |
| 38 | +[NOTE] |
| 39 | +==== |
| 40 | +As GitHub renders AsciiDoc files using https://asciidoctor.org/[AsciiDoctor], it is the current reference regarding AsciiDoc syntax we use in the documentation. |
| 41 | +==== |
| 42 | + |
| 43 | +=== Internal links |
| 44 | + |
| 45 | +For internal links to AsciiDoc file (repo documentation content), we use relative links with the `xref:` macro. |
| 46 | + |
| 47 | +``` |
| 48 | +xref:CONTRIBUTING.adoc[CONTRIBUTING] |
| 49 | +``` |
| 50 | + |
| 51 | +For internal links to non-AsciiDoc file (e.g: README files), we use relative links with the `link:` macro. |
| 52 | + |
| 53 | +``` |
| 54 | +link:examples/README.md[examples README] |
| 55 | +``` |
| 56 | + |
| 57 | +=== External links |
| 58 | + |
| 59 | +For external links, we use https://docs.asciidoctor.org/asciidoc/latest/macros/autolinks/[autolinks]. |
| 60 | + |
| 61 | +[TIP] |
| 62 | +==== |
| 63 | +Links that are used multiple times must be defined in the header using the `:uri-xxx:` reference format. This makes any future updates to the URI much simpler. |
| 64 | +
|
| 65 | +. Defining a link in the document header |
| 66 | +. Calling the reference |
| 67 | +
|
| 68 | +---- |
| 69 | +:uri-repo: https://github.com/oracle-terraform-modules/terraform-oci-logging |
| 70 | +
|
| 71 | +{uri-repo}[link caption] |
| 72 | +---- |
| 73 | +
|
| 74 | +==== |
| 75 | + |
| 76 | +=== Terraform registry requirements |
| 77 | + |
| 78 | +- README files must be in Markdown format |
| 79 | +- All links must use absolute path, relative links are not supported |
| 80 | + |
| 81 | +== Terraform code |
| 82 | + |
| 83 | +=== Case type, Files, Names |
| 84 | + |
| 85 | +- Use `snake_case` when naming Terraform files, variables and resources |
| 86 | +- If you need a new .tf file at the root of the module for better clarity, use this naming scheme: `<module_name>_<resources_group>`: e.g. `vcn_gateways.tf`, `vcn_defaultresources.tf` |
| 87 | +- If your variable is controlling a behaviour, use imperative style to name it: e.g. `create_internet_gateway` |
| 88 | + |
| 89 | +=== Variable blocks |
| 90 | + |
| 91 | +Variables should always be in the format below: |
| 92 | + |
| 93 | +. description. Add `(Updatable)` at the begining of the description if this value do not triggers a resource `recreate`) |
| 94 | +. type |
| 95 | +. default (if any) |
| 96 | + |
| 97 | +Do not hesitate to insert a brief comment in the variable block if it helps to clarify your intention. |
| 98 | + |
| 99 | +WARNING: No default value for `compartment_id` or any other variables related to provider authentication in module or examples files. The user will have to explicitly set these values. |
| 100 | + |
| 101 | +=== Examples |
| 102 | + |
| 103 | +Examples should promote good practices as much as possible: avoid creating resources in the tenancy root compartment. |
0 commit comments