Skip to content

Latest commit

 

History

History
105 lines (69 loc) · 3.83 KB

codingconventions.adoc

File metadata and controls

105 lines (69 loc) · 3.83 KB

Coding conventions

Table of Contents

This is a list of coding conventions you should observe when contributing code for this project.

Current conventions:

  • module structure

  • adopting the right case type

  • good names for files and terraform objects (resources, variables, outputs)

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.

Use PR comments and the GitHub suggestion feature to agree on the final result.

Module Structure

  • We adhere to the Terraform Standard Module Structure

  • Any nested module calls should be in the main file: main.tf is the primary entrypoint of the module

  • All variables and ouputs declarations should be in variables.tf and outputs.tf

  • All variables and outputs should have descriptions

  • Nested modules should exist under the modules/ folder

  • Examples of using the module should exist under the examples/ folder and have a README to explain the goal and usage of the example

Documentation format

We use AsciiDoc with the *.adoc file extension. The only exception is for the README files that need to be displayed on the Terraform Registry.

ℹ️

As GitHub renders AsciiDoc files using AsciiDoctor, it is the current reference regarding AsciiDoc syntax we use in the documentation.

Terraform Registry currently do not support AsciiDoc,so documentation content such as README files must be in Markdown format.

Internal links

For internal links to AsciiDoc file (repo documentation content), we use relative links with the xref: macro.

xref:CONTRIBUTING.adoc[CONTRIBUTING]

For internal links to non-AsciiDoc file (e.g: README files), we use relative links with the link: macro.

link:examples/README.md[examples README]

External links

For external links, we use autolinks.

💡

If a link is used mutiple times, prefer to add the link in the header with a reference in the format :uri-xxx:. This will facilitate updates in link destination is to be modified.

  1. Defining a link in the document header

  2. Calling the reference

:uri-repo: https://github.com/oracle-terraform-modules/terraform-oci-compute-instance

{uri-repo}[link caption]

Terraform registry specificities

  • README files must be in Markdown format

  • All links must use absolute path, relative links are not supported

Terraform code

Case type, Files, Names

  • Use snake_case when naming Terraform files, variables and resources

  • 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

  • If your variable is controlling a behaviour, use imperative style to name it: e.g. create_internet_gateway

Variable blocks

Variables should always be in the format below:

  1. description. Add (Updatable) at the begining of the description if this value do not triggers a resource recreate)

  2. type

  3. default (if any)

Do not hesitate to insert a brief comment in the variable block if it helps to clarify your intention.

⚠️
 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.

Examples

Examples should promote good practices as much as possible: avoid creating resources in the tenancy root compartment.