feat: add standard explaining conventional-commit types

Adds documetation around the use of conventional-commit messages. In particular, explaining how the types should be applied for terraform repos.
open-turo · May 18, 2023 · 509ece0 · 509ece0
1 parent e38581a
commit 509ece0
Show file tree

Hide file tree

Showing 6 changed files with 141 additions and 0 deletions.
diff --git a/docs/changes.md b/docs/changes.md
@@ -25,3 +25,24 @@ We use this document to allow us:
 
 In general, if you are proposing a new change we hope that the change is based on prior art and that you can provide
 examples of how the change is being used in the industry.
+
+## Conventional Commits
+
+The following table describes the meaning of our conventional commits within this standards repository. Our end goal
+is that the version of these standards roughly track with the standards, not the implementation of those standards.
+Implementation being the specific text and/or checks to enforce standars and policies. In those cases, a `fix` is enough
+to ensure a new version of the standards is released but not that the actual standards have meaningfully changed.
+
+| type     | creates release | description                                                                                    |
+| -------- | --------------- | ---------------------------------------------------------------------------------------------- |
+| feat     | yes             | Adding a new standard (Adding checks for standards IS NOT a `feat`)                            |
+| fix      | yes             | Modifying/improving an existing standard or adding/modifying checks for any existing standard  |
+| test     | no              | Modifying only test resources or the actual tests                                              |
+| docs     | no              | Changes to documentation - either descriptions & comments in `tf` files or in other docs files |
+| chore    | no              | Other changes that don't modify src or test files - modifying scripts                          |
+| ci       | no              | Changes to continuous integration - GHA workflows                                              |
+| refactor | no              | Changes which do not affect the public behavior                                                |
+| revert   | no              | Permanently revert a change                                                                    |
+| style    | no              | Changes due to code style, whitespace, or documentation linting                                |
+| build    | no              | Do not use - build is unused with terraform workspaces                                         |
+| perf     | no              | Do not use                                                                                     |
diff --git a/docs/convention-commits.md b/docs/convention-commits.md
@@ -0,0 +1,90 @@
+# Conventional Commit message structure
+
+Commit messages are expected to follow the conventional-commit standards as defined
+by [conventionalcommits.org](https://www.conventionalcommits.org/en/v1.0.0/).
+
+Terraform is not exactly `code` so the meaning of `fix` and `feat` are slightly different than in a code repository.
+This is expressed in the tables below.
+
+### Terraform workspaces
+
+The following table describes the meaning of our conventional commits within the usage of a Terraform workspace.
+
+| Type     | Release?               | Description                                                                             |
+| -------- | ---------------------- | --------------------------------------------------------------------------------------- |
+| feat     | :white-check-mark: yes | Adding resources                                                                        |
+| fix      | :white-check-mark: yes | Modifying an existing resource                                                          |
+| docs     | :x: no                 | Changes to documentation - both markdown files and comments                             |
+| chore    | :x: no                 | Changes that don't modify resource or test files - modifying scripts, repository config |
+| ci       | :x: no                 | Changes to continuous integration - GHA workflows                                       |
+| refactor | :x: no                 | Changes which do not affect the public behavior                                         |
+| revert   | :x: no                 | Permanently revert a change                                                             |
+| style    | :x: no                 | Changes due to code style, whitespace, or documentation linting                         |
+| build    | :x: no                 | Do not use - build is unused with terraform workspaces                                  |
+| perf     | :x: no                 | Do not use                                                                              |
+| test     | :x: no                 | Do not use - workspaces do not have tests                                               |
+
+#### Removing resources
+
+When removing a resource, you can choose whether or not you want it to be a `feat` or `fix`. This is a judgement call
+based on the size and scope of the change.
+
+- **fix** – When you are removing an unused and easily re-creatable or recoverable resource with no state
+  the change would be considered a fix. For example: removing an unused security group or IAM role.
+- **feat** – When you are removing a resource that has state where recreation would be substantial. For example:
+  removing an RDS instance.
+
+#### Scope
+
+- _may_ be `environment` when changes apply to one environment
+- _may_ be the type of file changed for chores (for example script or workflow)
+
+#### Breaking change
+
+A breaking change may be used to call out substantial changes that others might want to be made aware of.
+
+This is particularly important if there are other, external dependencies to the workspace - such as remote state - which
+require other workspaces to be updated in sync.
+
+### Terraform modules
+
+The following table describes the meaning of our conventional commits within the usage of a Terraform workspace.
+
+| type     | creates release | description                                                                                    |
+| -------- | --------------- | ---------------------------------------------------------------------------------------------- |
+| feat     | yes             | Adding new functionality and/or resources                                                      |
+| fix      | yes             | Modifying an existing resource or functionality                                                |
+| test     | no              | Modifying only test resources or the actual tests                                              |
+| docs     | no              | Changes to documentation - either descriptions & comments in `tf` files or in other docs files |
+| chore    | no              | Other changes that don't modify src or test files - modifying scripts                          |
+| ci       | no              | Changes to continuous integration - GHA workflows                                              |
+| refactor | no              | Changes which do not affect the public behavior                                                |
+| revert   | no              | Permanently revert a change                                                                    |
+| style    | no              | Changes due to code style, whitespace, or documentation linting                                |
+| build    | no              | Do not use - build is unused with terraform workspaces                                         |
+| perf     | no              | Do not use                                                                                     |
+
+#### Removing resources
+
+When removing a resource, you can choose whether or not you want it to be a `feat` or `fix`. This is a judgement call
+based on the size and scope of the change.
+
+- **fix** – When you are removing an unused and easily re-creatable or recoverable resource with no state
+  the change would be considered a fix. For example: removing an unused security group or IAM role.
+- **feat** – When you are removing a resource that has state where recreation would be substantial. For example:
+  removing an RDS instance.
+
+#### Breaking change
+
+This must be specified if the change will break any current usages of the module.
+
+This is best implemented through deprecation first to add new/replacement functionality followed up with remove of the
+now unused functionality.
+
+When creating a breaking change - you MUST include a markdown document in the `docs/breaking-changes` directory. It
+should be named `v<version>.md` where `<version>` is the new/breakign version. This document should explain the breaking
+change and how to migrate to the new version.
+
+#### Scope
+
+Use of scope is optional. It may reflect a fucntional area or component that matches the change.
diff --git a/docs/index.md b/docs/index.md
@@ -19,6 +19,9 @@ We use the following standards as a baseline for all Terraform code at Turo:
 - Scripts to rule them all -- we use [scripts to rule them all](https://github.com/github/scripts-to-rule-them-all) to
   provide consistent usage and functionality across all repositories.
 
+This document will attempt to summarize what is important and provide links to other sources for more details and
+examples.
+
 ## `pre-commit` configuration
 
 We expect that all tf repos will have the following pre-commit configuration:

diff --git a/docs/modules/breaking-changes.md b/docs/modules/breaking-changes.md
@@ -0,0 +1,10 @@
+# Breaking changes
+
+This must be specified if the change will break any current usages of the module.
+
+This is best implemented through deprecation first to add new/replacement functionality followed up with remove of the
+now unused functionality.
+
+When creating a breaking change - you **MUST** include a markdown document in the `docs/breaking-changes` directory. It
+should be named `v<version>.md` where `<version>` is the new/breakign version. This document should explain the breaking
+change and how to migrate to the new version.
diff --git a/docs/modules/index.md b/docs/modules/index.md
@@ -0,0 +1,13 @@
+# Modules
+
+We use modules for a few reasons:
+
+- To provide a consistent interface for common patterns
+- Abstract functionality into a single place
+- Allow for reuse
+
+See:
+
+- [breaking-changes](breaking-changes.md)
+- [input-variables](input-variables.md)
+- [output-variables](output-variables.md)
diff --git a/docs/style/README.md b/docs/style/README.md
@@ -0,0 +1,4 @@
+# Style
+
+- [conditional-resource-creation](conditional-resource-creation.md) - Creating resources based on variables
+- [control-blocks](control-blocks.md) - How to use advanced control in Terraform