Skip to content

Commit

Permalink
feat: initial repo setup and bootstrapping
Browse files Browse the repository at this point in the history
This creates the first hook and some initial standards.
  • Loading branch information
greenkiwi committed Nov 1, 2023
1 parent 4551aa3 commit 80e1604
Show file tree
Hide file tree
Showing 23 changed files with 590 additions and 0 deletions.
2 changes: 2 additions & 0 deletions .commitlintrc.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
extends:
- "@open-turo/commitlint-config-conventional"
8 changes: 8 additions & 0 deletions .fotingorc
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
{
"git": {
"baseBranch": "main"
},
"github": {
"baseBranch": "main"
}
}
1 change: 1 addition & 0 deletions .github/CODEOWNERS
Validating CODEOWNERS rules …
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
* @open-turo/github-actions
6 changes: 6 additions & 0 deletions .github/dependabot.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
version: 2
updates:
- package-ecosystem: github-actions
directory: /
schedule:
interval: daily
31 changes: 31 additions & 0 deletions .github/workflows/ci.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
name: CI

on:
pull_request:
branches: [main]
workflow_dispatch:

jobs:
lint:
name: Lint
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: mfinelli/setup-shfmt@v3
- name: Install actionlint
uses: open-turo/action-install-release@v1
with:
repository: rhysd/actionlint
- name: Pre-commit
uses: open-turo/action-pre-commit@v1

test:
name: Test
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- run: script/test
80 changes: 80 additions & 0 deletions .github/workflows/release.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
# Sample workflow for building and deploying a MkDocs site to GitHub Pages
name: Deploy MkDocs with GitHub Pages dependencies preinstalled

on:
# Runs on pushes targeting the default branch
push:
branches: ["main", "v.*"]

# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
contents: write
pages: write
id-token: write

# Allow one concurrent deployment
concurrency:
group: "pages"
cancel-in-progress: true

jobs:
test:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- run: script/test

# Build job
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Setup Pages
uses: actions/configure-pages@v3
- name: Setup Python
uses: actions/setup-python@v4
with:
python-version: "3.11"
- name: Install MkDocs and Material for MkDocs
run: pip install mkdocs[i18n] mkdocs-material
- name: Install Pillow and CairoSVG (required for social card generation)
run: pip install mkdocs-material
- name: Semantic Release
uses: cycjimmy/semantic-release-action@v4
with:
# You can specify specifying version range for the extra plugins if you prefer.
extra_plugins: |
@open-turo/semantic-release-config
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

- name: Setup caching
uses: actions/cache@v3
with:
key: ${{ github.sha }}
path: .cache
- name: Build site (_site directory name is used for Jekyll compatiblity)
run: mkdocs build --config-file ./mkdocs.yml --site-dir ./_site
- name: Upload artifact
uses: actions/upload-pages-artifact@v2

# Deployment job
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
needs:
- build
- test
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v1
7 changes: 7 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# IntelliJ IDEA
.idea/

# Crash log files
crash.log

.test/
31 changes: 31 additions & 0 deletions .pre-commit-config.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v3.4.0 # Use the ref you want to point at
hooks:
- id: check-json
- id: check-yaml
- id: pretty-format-json
args:
- --autofix
- id: end-of-file-fixer
- id: trailing-whitespace
- repo: https://github.com/pre-commit/mirrors-prettier
rev: v2.3.0
hooks:
- id: prettier
stages: [commit]
- repo: https://github.com/alessandrojcm/commitlint-pre-commit-hook
rev: v4.1.0
hooks:
- id: commitlint
stages: [commit-msg]
additional_dependencies: ["@open-turo/commitlint-config-conventional"]
- repo: https://github.com/rhysd/actionlint
rev: v1.6.23
hooks:
- id: actionlint
- repo: https://github.com/jumanjihouse/pre-commit-hooks
rev: 3.0.0 # or specific git tag
hooks:
- id: shellcheck
- id: shfmt
6 changes: 6 additions & 0 deletions .pre-commit-hooks.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
- id: action-docs
name: "Update action README"
description: "Runs action-docs to update the README.md for each action.yaml file"
entry: hooks/action-docs/check
language: script
files: \.action.yaml$
3 changes: 3 additions & 0 deletions .releaserc.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
{
"extends": "@open-turo/semantic-release-config"
}
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,2 +1,3 @@
# github-actions-standards

Turo development standards when using GitHub Actions.
48 changes: 48 additions & 0 deletions docs/changes.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
# Changes & Updates to the Standards

Our development standards and best practices are always evolving. This repository is the source of truth for the
standards and best practices we use at Turo. This document is a changelog of the changes and updates to the standards as
well as the toll that we use the make these changes.

If you have a suggestion for a change or update to the standards, please open an issue in this repository.

Changes are managed through pull requests and merged using
the [Rebase & Merge](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-request-merges#rebase-and-merge-your-pull-request-commits)
workflow.

## Guidelines for changes

At Turo we believe in convention & prior art over configuration and bespoke creations. To that end, we try to base our
standards and practices off of industry standards and best practices. When making changes to the standards or
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

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 |
90 changes: 90 additions & 0 deletions docs/convention-commits.md
Original file line number Diff line number Diff line change
@@ -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.
65 changes: 65 additions & 0 deletions docs/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
# Turo Terraform Development Standards

## Baseline standards

We use the following standards as a baseline for all Terraform code at Turo:

- [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/)
- [Rebase & Merge](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-request-merges#rebase-and-merge-your-pull-request-commits)
workflow
- [pre-commit](https://pre-commit.com/) for linting
- [mkdocs](https://www.mkdocs.org/) for documentation -- For full documentation
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.
- 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:

```yaml
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v4.1.0 # Use the ref you want to point at
hooks:
- id: check-json
- id: check-yaml
- id: pretty-format-json
args:
- --autofix
- id: end-of-file-fixer
- id: trailing-whitespace
- repo: https://github.com/pre-commit/mirrors-prettier
rev: v2.5.1
hooks:
- id: prettier
stages: [commit]
- repo: https://github.com/alessandrojcm/commitlint-pre-commit-hook
rev: v8.0.0
hooks:
- id: commitlint
stages: [commit-msg]
additional_dependencies: ["@open-turo/commitlint-config-conventional"]
- repo: https://github.com/rhysd/actionlint
rev: v1.6.8
hooks:
- id: actionlint
- repo: https://github.com/jumanjihouse/pre-commit-hooks
rev: 3.0.0 # or specific git tag
hooks:
- id: shellcheck
- id: shfmt
- repo: https://github.com/open-turo/github-actions-standards
rev: v1.0.0
hooks:
- id: action-docs
```
4 changes: 4 additions & 0 deletions docs/sources.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
# Sources of Inspiration

- https://developer.hashicorp.com/terraform/language
- https://www.terraform-best-practices.com/
Loading

0 comments on commit 80e1604

Please sign in to comment.