Skip to content

Commit

Permalink
fix: first pass updating docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@greenkiwi
greenkiwi committed Nov 1, 2023
1 parent 80e1604 commit 8a7bdbc
Show file tree
Hide file tree
Showing 7 changed files with 124 additions and 155 deletions.
4 changes: 3 additions & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
# github-actions-standards
# GitHub Actions Standards

Turo development standards when using GitHub Actions.

See [docs](./docs)
72 changes: 72 additions & 0 deletions docs/action-repos.md
View file
Original file line number Diff line number Diff line change
@@ -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.
30 changes: 14 additions & 16 deletions docs/changes.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.<function>.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.
Expand All @@ -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 |
92 changes: 21 additions & 71 deletions docs/convention-commits.md
View file
Original file line number Diff line number Diff line change
@@ -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<version>.md` where `<version>` is the new/breakign version. This document should explain the breaking
should be named `v<version>.md` where `<version>` 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.
9 changes: 4 additions & 5 deletions docs/index.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Turo Terraform Development Standards
# Turo GitHub Actions Development Standards

## Baseline standards

Expand All @@ -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.

Expand Down
3 changes: 1 addition & 2 deletions docs/sources.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@
# Sources of Inspiration

- https://developer.hashicorp.com/terraform/language
- https://www.terraform-best-practices.com/
-
69 changes: 9 additions & 60 deletions docs/versioning.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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<major>` 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.

0 comments on commit 8a7bdbc

Please sign in to comment.