diff --git a/README.md b/README.md index 8f1c054..30b1984 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,5 @@ -# github-actions-standards +# GitHub Actions Standards Turo development standards when using GitHub Actions. + +See [docs](./docs) diff --git a/docs/action-repos.md b/docs/action-repos.md new file mode 100644 index 0000000..9f0ff9f --- /dev/null +++ b/docs/action-repos.md @@ -0,0 +1,72 @@ +# Action Repos + +Open-Turo has two different types of action repos: + +- single actions +- action suites + +## Single action repos + +These are the default standard for actions. They are appropriate when you have a standalone action that does not have +other related actions. Examples of this: + +- [action-pre-commit]() +- [action-???] + +## Action Suites + +We have found that it is quite common to want to have sets of related actions that either apply to a platform (jvm, +node, terraform, etc.) or apply to a function (semantic-release). In these cases, we use directories inside of action +repos to group actions together. + +For example, the actions-jvm repo provides four different high level actions: + +- lint +- test +- prerelease +- build-docker + +This provides two functions: + +1. it groups like actions together where they are easier to maintain +2. the high level actions allow for code repos to have very simple github action workflow files + +There is an example of a jvm based repo's CI yaml file + +```yaml +name: CI + +on: + pull_request: + branches: + - main + +jobs: + lint: + name: Lint + runs-on: [self-hosted, general-ubuntu] + steps: + - uses: open-turo/actions-jvm/lint@v1 + with: + checkout-repo: true + github-token: ${{ secrets.GITHUB_TOKEN }} + artifactory-username: ${{ secrets.ARTIFACTORY_USERNAME }} + artifactory-auth-token: ${{ secrets.ARTIFACTORY_AUTH_TOKEN }} + + test: + name: Test + runs-on: [self-hosted, general-ubuntu] + steps: + - uses: open-turo/actions-jvm/test@v1 + with: + checkout-repo: true + github-token: ${{ secrets.GITHUB_TOKEN }} + artifactory-username: ${{ secrets.ARTIFACTORY_USERNAME }} + artifactory-auth-token: ${{ secrets.ARTIFACTORY_AUTH_TOKEN }} +``` + +### Language & Platform Action Suites + +When creating actions for repos, we suggest erring on the side of having simple action workflow files in the workflows +that utilize appropriate action suites to abstract away functionality. This makes it easier for people to onboard new +repositories and makes it easier to perform maintenance actions across all repos that are using these actions. diff --git a/docs/changes.md b/docs/changes.md index 72866d3..4cf8b8f 100644 --- a/docs/changes.md +++ b/docs/changes.md @@ -19,9 +19,7 @@ substantial existing prior art. We use this document to allow us: - To clarify how an existing standard might be applied -- To extend an existing pattern where we see a need -- for example: allowing for splitting `variables.tf` into - multiple `variables..tf` files. -- To define best practices where we have found no prior examples or subtantial prior art +- To define best practices where we have found no prior examples or substantial prior art 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. @@ -33,16 +31,16 @@ is that the version of these standards roughly track with the standards, not the 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 | +| 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 `yaml` 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 index 5cb1719..f064671 100644 --- a/docs/convention-commits.md +++ b/docs/convention-commits.md @@ -1,90 +1,40 @@ # Conventional Commit message structure -Commit messages are expected to follow the conventional-commit standards as defined +Commit messages in code repositories 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. +### GitHub Actions -### Terraform workspaces +The following table describes the meaning of our conventional commits within the usage of a GitHub Action repository. -The following table describes the meaning of our conventional commits within the usage of a Terraform workspace. +Remember that the purpose of conventional commits is to track the API changes. In the case of GitHub actions, that +includes the inputs, outputs, functional behavior, calling context etc. -| 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. +| Type | Release? | Description | +| -------- | ---------------------- | ------------------------------------------------------------------------------------------------ | +| feat | :white-check-mark: yes | Adding new functionality, in particular to the API. New inputs & outputs would be a new feature. | +| fix | :white-check-mark: yes | Modifying existing functionality or fixing a bug. | +| 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 - use CI instead | +| perf | :x: no | Do not use | +| test | :x: no | Do not use - deployments do not have tests at this time. | #### 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. +- undefined at this time #### Breaking change -This must be specified if the change will break any current usages of the module. +This must be specified if the change will break any current usages of the GitHub action. 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.md` where `` is the new/breakign version. This document should explain the breaking +should be named `v.md` where `` is the new/breaking 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 index 962a8ab..dcb35e9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,4 +1,4 @@ -# Turo Terraform Development Standards +# Turo GitHub Actions Development Standards ## Baseline standards @@ -12,10 +12,9 @@ We use the following standards as a baseline for all Terraform code at Turo: visit [mkdocs.org](https://www.mkdocs.org). - Formatting -- all files are formatted using appropriate language specific tools during the pre-commit phase to ensure baseline style is consistent. -- Terraform Documentation -- all Terraform code is documented using the [terraform_docs](https://terraform-docs.io/) -- Standards are enforced with code whereever possible. For example, we use [pre-commit](https://pre-commit.com/) to - enforce - formatting and linting standards. +- Action Documentation -- all actions are to be documented using the [action-docs](https://github.com/npalm/action-docs) +- Standards are enforced with code where ever possible. For example, we use [pre-commit](https://pre-commit.com/) to + enforce formatting and linting standards. - 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. diff --git a/docs/sources.md b/docs/sources.md index 99ffe60..1498a76 100644 --- a/docs/sources.md +++ b/docs/sources.md @@ -1,4 +1,3 @@ # Sources of Inspiration -- https://developer.hashicorp.com/terraform/language -- https://www.terraform-best-practices.com/ +- diff --git a/docs/versioning.md b/docs/versioning.md index 4aa8371..59644c8 100644 --- a/docs/versioning.md +++ b/docs/versioning.md @@ -2,68 +2,17 @@ We have the following guidance for versioning within our repositories. -## Lock files +## Pin to major versions -We check in lock files for all our projects. This is to ensure that we are all using the same versions of -dependencies.This is especially important for our libraries, as we want to ensure that the version of a library that we -are using is the same version that our consumers are using. +Per GitHub best practices, we expect that a branch will be created with `v` that is updated to track the current +release for each major branch that has been released. -We lock two platform: +## Maintenance cycle -1. `linux_amd64` for our CI & Terraform Cloud agent platform -2. `darwin_amd64` for our local development platform -- note that `arm` support is not consistent enough for us to use - that for local development. That may change in the future. +We generally strive to keep people on the most recent branch. Older usages should move to more recent versions as soon +as is possible. -Locking can be performed with the following command: +### Renovate Bot -```hcl -terraform -chdir = "$TERRAFORM_DIR" providers lock -platform = darwin_amd64 -platform = linux_amd64 -``` - -Where `$TERRAFORM_DIR` is the directory containing the Terraform code. - -## Provider Version Constraints - -Here are the conventions we use when specifying the version of a given Terraform provider. The thought is that by having -only minimum versions specified in our Terraform modules, we can update the provider version in a Terraform workspace -without having to release new versions of our Terraform modules. - -In general, when using version constraint pinning syntax, pin to the major version. e.g. `version = "~> 3.5"`. - -`version = ">= 5.0.0, <6.0.0"` - -See here for details for how Terraform interprets version constraints. - -## Terraform Workspaces - -Use major version pinning here. Use the ~> syntax to allow the rightmost version number to vary as new provider releases -become available. e.g. `version = "~> 3.5"` which indicates any version is acceptable from the `3.x` series, as long as the -version is `3.5` or higher. - -## Terraform Modules - -Use the `>=` syntax to allow the version specified to be a minimum. e.g. `version = ">= 3.5.0"` which indicates version -`3.5.0` or later, including `3.6`, `4.0`, etc. - -This is true unless we know that the module will not be compatible with a future version of the provider. - -## Tests within Terraform Modules - -Use major version pinning here. Use the `~>` syntax to allow the rightmost version number to vary as new provider releases -become available. e.g. `version = "~> 3.5"` which indicates any version is acceptable from the `3.x` series, as long as the -version is `3.5` or higher. - -## CI Validation - -We expect that repos will perform the following linting steps during the pre-commit and CI process. - -```hcl - - repo: https://github.com/antonbabenko/pre-commit-terraform - rev: v1.77.1 - hooks: - - id: terraform_providers_lock - stages: [commit] - args: - - --args=-platform=darwin_amd64 - - --args=-platform=linux_amd64 -``` +Future: We should have clear instructions and expectations around using renovate bot to keep actions up to date with +latest versions.