Skip to content

Commit 30fd5e8

Browse files
docs: Add contributing documentation (#35)
* docs: Add contributing documentation Signed-off-by: Darren Murray <[email protected]> * docs: Address code review comments Signed-off-by: Darren Murray <[email protected]> * docs: Fix typo
1 parent 0ae3dd6 commit 30fd5e8

File tree

6 files changed

+275
-2
lines changed

6 files changed

+275
-2
lines changed

.github/ISSUE_TEMPLATE/bug_report.md

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
name: Bug report
3+
about: Create a report to help us improve
4+
title: 'bug:'
5+
labels: bug
6+
---
7+
8+
**Describe the bug**
9+
A clear and concise description of what the bug is.
10+
11+
**Steps to reproduce**
12+
13+
14+
**Expected behavior**
15+
A clear and concise description of what you expected to happen.
16+
17+
**Screenshots**
18+
If applicable, add screenshots to help explain your problem.
19+
20+
**Please complete the following information):**
21+
- Terraform Version: [e.g. v1.0.0 ]
22+
- Module Version [e.g. v0.15.0]
23+
24+
Run `terraform version` to find your Terraform version.
25+
You can find the module version by running `terraform providers` or in your terraform configuration. If developing locally you can check the `VERSION` file in the project root directory.
26+
27+
**Additional context**
28+
Add any other context about the problem here.
Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
name: Feature request
3+
about: Suggest an idea for this project
4+
title: 'feat: '
5+
labels: 'feat'
6+
---
7+
8+
# Feature Request
9+
10+
**Describe the Feature Request**
11+
A clear and concise description of what the feature request is. Please include if your feature request is related to a problem
12+
13+
**Is your feature request related to a problem? Please describe**
14+
Problems related that made you consider this feature request
15+
16+
**Describe Preferred Solution**
17+
A clear and concise description of what you want to happen and alternatives
18+
19+
**Additional Context**
20+
List any other information that is relevant to your issue. Stack traces, related issues, suggestions on how to add, use case, Stack Overflow links, forum links, screenshots, OS if applicable, etc.

.github/pull-request-template.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
name: Pull request template
3+
about: 'type(scope): Subject of the pull request '
4+
---
5+
6+
***Issue***: Include link to the Jira/Github Issue
7+
8+
***Description:***
9+
Provide a detailed description of the changes made by this pull request.
10+
11+
***Additional Info:***
12+
Include any other relevant information such as how to use the new fuctionality, screenshots, etc.
13+

CONTRIBUTING.md

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Contributing to the Lacework Terraform Modules
2+
3+
### Table Of Contents
4+
5+
* [Before getting started?](#before-getting-started)
6+
7+
* [How to Contribute?](#how-can-i-contribute)
8+
* [Reporting Bugs](#reporting-bugs)
9+
* [Feature Requests](#feature-requests)
10+
* [Pull Requests](#creating-a-pull-request)
11+
12+
* [Developer Guidelines](/DEVELOPER_GUIDELINES.md)
13+
14+
15+
## Before getting started
16+
17+
Read the [README.md](README.md) and
18+
Hashicorps [best practices and syntax guidelines](https://www.terraform.io/docs/configuration/index.html)
19+
20+
## Reporting Bugs
21+
22+
Ensure the issue you are raising has not already been created under [issues](https://github.com/lacework/terraform-kubernetes-agent/issues).
23+
If no current issue addresses the problem, open a new [issue](https://github.com/lacework/terraform-kubernetes-agent/issues/new).
24+
Include as much relevant information as possible. See the [bug template](https://github.com/lacework/terraform-kubernetes-agent/blob/main/.github/ISSUE_TEMPLATE/bug_report.md) for help on creating a new issue.
25+
26+
## Feature Requests
27+
28+
If you wish to submit a request to add new functionality or an improvement to a terraform module then use the the [feature request](https://github.com/lacework/terraform-kubernetes-agent/blob/main/.github/ISSUE_TEMPLATE/feature_request.md) template to
29+
open a new [issue](https://github.com/lacework/terraform-kubernetes-agent/issues/new)
30+
31+
## Creating a Pull Request
32+
33+
If you have made a change or added new functionality, you can submit a pull request. The project maintainers will aim to review in a 2 week timeframe. When submitting a pull request please read the [developer guidelines](/DEVELOPER_GUIDELINES.md)
34+
35+
The examples folder contains Terraform code that run as part of the CI pipeline. A new pull request will trigger this test run to ensure no breaking changes are added. We recommended sanity checking your own Terraform changes before submitting the change for review.
36+
37+
38+
Thanks,
39+
40+
Project Maintainers

DEVELOPER_GUIDELINES.md

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
## Terraform Modules Developer Guidelines
2+
3+
### Installation
4+
It is recommended to use tfenv or tfswitch. This makes managing and switching between Terraform versions quick and easy.
5+
6+
***TFenv***
7+
8+
```brew install tfenv```
9+
To get up and running with TFenv refer to the Usage section of the README
10+
11+
***TFSwitch***
12+
13+
```brew install warrensbox/tap/tfswitch```
14+
To get up and running with TFSwitch refer to the documentation
15+
16+
***Indentation***
17+
18+
Use two spaces, no tabs.
19+
20+
```hcl
21+
resource "aws_instance" "example" {
22+
ami = "abc123"
23+
24+
network_interface {
25+
# ...
26+
}
27+
}
28+
```
29+
30+
***Comments***
31+
32+
Our best practice is to add a comment for every resource declared. This comment should explain what the resource is doing and how it interconnects with other resources. Hashicorp recommends using # for single-line comments.
33+
34+
Here is an example of a resource with its comment:
35+
36+
```hcl
37+
# Create the Lacework application within Azure Active Directory to grant
38+
# access to Azure Storage, Azure Key Vault, AAD Graph API, and Microsoft Graph
39+
resource "azuread_application" "default" {
40+
...
41+
}
42+
```
43+
44+
45+
***Input Variables***
46+
47+
Always document user-facing variables, even if your variable names are self-descriptive like api_key or account, they could be easily misinterpreted. Always add a description field with a brief explanation.
48+
49+
A couple of examples:
50+
51+
52+
```hcl
53+
variable "account" {
54+
type = string
55+
description = "Lacework account subdomain of URL (i.e. <ACCOUNT>.lacework.net)"
56+
}
57+
```
58+
59+
```hcl
60+
variable "api_key" {
61+
type = string
62+
description = "A Lacework API access key"
63+
}
64+
```
65+
Additionally, any required variables like api keys, or required tagging should not have default values, and should require the user to input those either manually each run, or optimally using a terraform.tfvars file
66+
67+
***Recommended Project File Organization***
68+
69+
A few best practices for organizing Terraform projects:
70+
71+
* `main.tf` - Store the main structure of your terraform code in this file
72+
* `variables.tf` - All variables for your project
73+
* `output.tf` - All outputs in this file
74+
* `tfvars.example` - An example terraform.tfvars file for easy cp for users (note: *.tfvars are typically
75+
ignored by .gitignore
76+
* `.gitignore` - Critical to ensure that any sensitive information used in tfvars are not checked in to git
77+
78+
79+
***Version Support / Documentation***
80+
81+
Hashicorp release frequent patch and minor updates as needed, as well as new major releases of Terraform each year. Although Hashicorp provide solid documentation on how to upgrade between major releases of Terraform, Lacework must contend with the fact that Lacework customers do not all upgrade in a timely manor. For this reason Tech Alliances Team must continue to update documentation with supported versions of Terraform, as well as update CI pipelines to test changes across each supported version.
82+
83+
***Standard Versioning for Code Snippets***
84+
All customer facing code snippets should adhere to the standard of using pessimistic version constraint to minor releases.
85+
86+
```hcl
87+
module "aws_config" {
88+
source = "lacework/config/aws"
89+
version = "~> 0.1"
90+
}
91+
```
92+
```hcl
93+
module "aws_cloudtrail" {
94+
source = "lacework/cloudtrail/aws"
95+
version = "~> 0.1"
96+
97+
bucket_force_destroy = true
98+
use_existing_iam_role = true
99+
iam_role_name = module.aws_config.iam_role_name
100+
iam_role_arn = module.aws_config.iam_role_arn
101+
iam_role_external_id = module.aws_config.external_id
102+
}
103+
```
104+
105+
The example above will work for version 0.1.9 as well as 0.4.0, but will not pull in any major releases such as 1.0.0.
106+
107+
For more information visit [Semantic Versioning 2.0.0](https://semver.org/)
108+
109+
## Commit message standard
110+
111+
The format is:
112+
113+
```
114+
type(scope): subject
115+
BODY
116+
FOOTER
117+
```
118+
Each commit message consists of a header, body, and footer. The header is mandatory, the scope is optional, the type and subject are mandatory.
119+
When writing a commit message try and limit each line of the commit to a max of 100 hundred characters, so it can be read easily.
120+
121+
### Type
122+
123+
| Type | Description |
124+
| ----- | ----------- |
125+
| feat: | A new feature you're adding |
126+
| fix: |A bug fix|
127+
| style: | Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) |
128+
| refactor: | A code change that neither fixes a bug nor adds a feature |
129+
| test: | Everything related to testing |
130+
| docs: | Everything related to documentation |
131+
| chore: | Regular code maintenance |
132+
| build: | Changes that affect the build |
133+
| ci: | Changes to our CI configuration files and scripts |
134+
| perf: | A code change that improves performance |
135+
| metric: | A change that provides better insights about the adoption of features and code statistics |
136+
137+
### Scope
138+
The optional scope refers to the section that this commit belongs to, for example, changing a specific component or service, a directive, pipes, etc.
139+
Think about it as an indicator that will let the developers know at first glance what section of your code you are changing.
140+
141+
A few good examples are:
142+
143+
feat(client):
144+
docs(cli):
145+
chore(tests):
146+
ci(directive):
147+
148+
### Subject
149+
The subject should contain a short description of the change, and written in present-tense, for example, use “add” and not “added”, or “change” and not “changed”.
150+
I like to fill this sentence below to understand what should I put as my description of my change:
151+
152+
If applied, this commit will ________________________________________.
153+
154+
### Body
155+
The body should contain a longer description of the change, try not to repeat the subject and keep it in the present tense as above.
156+
Put as much context as you think it is needed, don’t be shy and explain your thought process, limitations, ideas for new features or fixes, etc.
157+
158+
### Footer
159+
The footer is used to reference issues, pull requests or breaking changes, for example, “Fixes ticket #123”.
160+
161+
## Signing commits
162+
Signed commits are required for any contribution to this project. Please see Github's documentation on configuring signed commits, [tell git about your signing key](https://docs.github.com/en/github/authenticating-to-github/managing-commit-signature-verification/telling-git-about-your-signing-key) and [signing commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits)

GNUmakefile

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,17 @@
1+
.PHONY: help
2+
help:
3+
@echo "-------------------------------------------------------------------"
4+
@echo "Lacework terraform-kubernetes-agent Makefile helper:"
5+
@echo ""
6+
@grep -Fh "##" $(MAKEFILE_LIST) | grep -v grep | sed -e 's/\\$$//' | sed -E 's/^([^:]*):.*##(.*)/ \1 -\2/'
7+
@echo "-------------------------------------------------------------------"
8+
19
default: ci
210

3-
ci:
11+
.PHONY: ci
12+
ci: ## *CI ONLY* Runs tests on CI pipeline
413
scripts/ci_tests.sh
514

6-
release: ci
15+
.PHONY: release
16+
release: ci ## *CI ONLY* Prepares a release of the Terraform module
717
scripts/release.sh prepare

0 commit comments

Comments
 (0)