feat: finish contributor guide

bschaatsbergen · Apr 4, 2024 · 83da73e · 83da73e
1 parent bc49ef5
commit 83da73e
Show file tree

Hide file tree

Showing 9 changed files with 62 additions and 79 deletions.
diff --git a/README.md b/README.md
@@ -30,72 +30,16 @@ variable "ebs_volume_size" {
 }
 ```
 
-## Documentation, questions and discussions
+## Documentation
 
 Official documentation on how to use this provider can be found on the 
 [Terraform Registry](https://registry.terraform.io/providers/bschaatsbergen/assert/latest/docs).
 In case of specific questions or discussions, please [open an issue](https://github.com/bschaatsbergen/terraform-provider-assert/issues/new) in this repository.
 
-## Requirements
+## Contributing
 
-* [Terraform](https://www.terraform.io/downloads)
-* [Go](https://go.dev/doc/install) (1.21)
-* [GNU Make](https://www.gnu.org/software/make/)
-* [golangci-lint](https://golangci-lint.run/usage/install/#local-installation) (optional)
-
-## Development
-
-### Building
-
-1. `git clone` this repository and `cd` into its directory
-2. `make` will trigger the Golang build
-
-The provided `GNUmakefile` defines additional commands generally useful during development,
-like for running tests, generating documentation, code formatting and linting.
-Taking a look at it's content is recommended.
-
-### Testing
-
-In order to test the provider, you can run
-
-* `make test` to run provider tests
-* `make testacc` to run provider acceptance tests
-
-It's important to note that acceptance tests (`testacc`) will actually spawn
-`terraform` and the provider. Read more about they work on the
-[official page](https://www.terraform.io/plugin/sdkv2/testing/acceptance-tests).
-
-### Generating documentation
-
-This provider uses [terraform-plugin-docs](https://github.com/hashicorp/terraform-plugin-docs/)
-to generate documentation and store it in the `docs/` directory.
-Once a release is cut, the Terraform Registry will download the documentation from `docs/`
-and associate it with the release version. Read more about how this works on the
-[official page](https://www.terraform.io/registry/providers/docs).
-
-Use `make generate` to ensure the documentation is regenerated with any changes.
-
-### Using a development build
-
-If [running tests and acceptance tests](#testing) isn't enough, it's possible to set up a local terraform configuration
-to use a development builds of the provider. This can be achieved by leveraging the Terraform CLI
-[configuration file development overrides](https://www.terraform.io/cli/config/config-file#development-overrides-for-provider-developers).
-
-First, use `make install` to place a fresh development build of the provider in your
-[`${GOBIN}`](https://pkg.go.dev/cmd/go#hdr-Compile_and_install_packages_and_dependencies)
-(defaults to `${GOPATH}/bin` or `${HOME}/go/bin` if `${GOPATH}` is not set). Repeat
-this every time you make changes to the provider locally.
-
-Then, setup your environment following [these instructions](https://www.terraform.io/plugin/debugging#terraform-cli-development-overrides)
-to make your local terraform use your local build.
-
-## Releasing
-
-The release process is automated via GitHub Actions, and it's defined in the Workflow
-[release.yml](./.github/workflows/release.yml).
-
-Each release is cut by pushing a [semantically versioned](https://semver.org/) tag to the default branch.
+If you are interested in contributing to this project, please check out the [contributor guide](https://bschaatsbergen.github.io/terraform-provider-assert/).
 
 ## License
 
-[Mozilla Public License v2.0](./LICENSE)
+[Mozilla Public License v2.0](./LICENSE)
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -1,5 +1,5 @@
-site_name: Terraform Assert Provider - Usage Guide
-site_description: 'Usage and contribution guide for the Terraform Assert Provider'
+site_name: Terraform Assert Provider - Contributor Guide
+site_description: 'Contributor guide for the Terraform Assert Provider'
 copyright: HashiCorp
 repo_name: bschaatsbergen/terraform-provider-assert
 repo_url: https://github.com/bschaatsbergen/terraform-provider-assert
@@ -9,10 +9,12 @@ docs_dir: mkdocs
 
 nav:
   - Welcome: index.md
-  - Usage: usage.md
   - Contribute:
       - Development Environment: development-environment.md
       - New Function: add-a-new-function.md
+      - Testing: testing.md
+      - Generating Documentation: generating-documentation.md
+      - Releasing: releasing.md
   - Submit an Issue: issue-reporting-and-lifecycle.md
   - FAQ: faq.md
 

diff --git a/mkdocs/README.md b/mkdocs/README.md
@@ -1,6 +1,6 @@
 # Documentation
 
-This directory contains documentation for the [Terraform Assert Provider Usage Guide](https://bschaatsbergen.github.io/terraform-provider-assert/).
+This directory contains documentation for the [Terraform Assert Provider Contributor Guide](https://bschaatsbergen.github.io/terraform-provider-assert/).
 
 ## Local Development
 

diff --git a/mkdocs/add-a-new-function.md b/mkdocs/add-a-new-function.md
@@ -23,7 +23,7 @@ For a new function use a branch named `f-{function name}`, for example, `f-equal
 ### Create and name the function
 
 The function name should be descriptive of its functionality and succinct.
-Existing examples include `not_null`, `equals`, and `contains`.
+Existing examples include `null`, `equals`, and `contains`.
 
 New functions can be created by copying the format of an existing function inside `internal/provider`.
 
@@ -33,9 +33,9 @@ The function struct's `Definition` method will document the expected parameters
 Parameter names and return values should be specified in `camel_case`.
 
 ```go
-func (r NotNullFunction) Definition(_ context.Context, _ function.DefinitionRequest, resp *function.DefinitionResponse) {
+func (r NullFunction) Definition(_ context.Context, _ function.DefinitionRequest, resp *function.DefinitionResponse) {
 	resp.Definition = function.Definition{
-		Summary: "Checks whether a given argument is not null",
+		Summary: "Checks whether a given argument is null",
 		Parameters: []function.Parameter{
 			function.DynamicParameter{
 				AllowNullValue:     true,
@@ -57,7 +57,7 @@ The function struct's `Run` method will contain the function logic.
 This includes processing the arguments, setting the return value, and any data processing that needs to happen in between.
 
 ```go
-func (r NotNullFunction) Run(ctx context.Context, req function.RunRequest, resp *function.RunResponse) {
+func (r NullFunction) Run(ctx context.Context, req function.RunRequest, resp *function.RunResponse) {
 	var argument types.Dynamic
 
 	resp.Error = function.ConcatFuncErrors(req.Arguments.Get(ctx, &argument))
@@ -77,12 +77,12 @@ This is done by adding the function to the `Functions` method in `internal/provi
 ```go
 func (p *AssertProvider) Functions(ctx context.Context) []func() function.Function {
 	return []func() function.Function{
-		NewNotNullFunction,
+		NewNullFunction,
 	}
 }
 ```
 
-### Write passing acceptance tests
+### Write passing tests
 
 All functions should have corresponding acceptance tests.
 For functions with variadic arguments, or which can potentially return an error, tests should be written to exercise those conditions.
@@ -103,7 +103,7 @@ import (
 	"github.com/hashicorp/terraform-plugin-testing/tfversion"
 )
 
-func TestIsNullFunction(t *testing.T) {
+func TestNullFunction(t *testing.T) {
 	t.Parallel()
 	resource.UnitTest(t, resource.TestCase{
 		TerraformVersionChecks: []tfversion.TerraformVersionCheck{
@@ -114,10 +114,10 @@ func TestIsNullFunction(t *testing.T) {
 			{
 				Config: `
 locals {
-  something = null
+  example = null
 }
-output "test" {
-  value = provider::assert::null(local.something)
+output "is_null" {
+  value = provider::assert::null(locals.example)
 }
 				`,
 				Check: resource.ComposeAggregateTestCheckFunc(

diff --git a/mkdocs/development-environment.md b/mkdocs/development-environment.md
@@ -1,27 +1,29 @@
 # Development Environment Setup
 
+If running tests and acceptance tests isn't enough, it's possible to set up a local terraform configuration to use a development builds of the provider. This can be achieved by leveraging the Terraform CLI configuration file development overrides.
+
 ## Requirements
 
 - [Terraform](https://www.terraform.io/downloads.html) 1.8+ (to run acceptance tests)
 - [Go](https://golang.org/doc/install) >=1.21 (to build the provider plugin)
 
 ### Building the Provider
 
-To compile the provider, run `make build`.
+To place a fresh development build of the provider in your `${GOBIN}` (defaults to `${GOPATH}/bin` or `${HOME}/go/bin` if `${GOPATH}` is not set), run:
 
 ```console
 make build
 ```
 
-This will build the provider and put the provider binary in the `$GOPATH/bin` directory.
+This will build the provider and put the provider binary in the `${GOBIN}` directory.
 
 ```console
 ls -la ./$GOPATH/bin/terraform-provider-assert
 ```
 
 ### Testing the Provider
 
-In order to test the provider, you can run `make test`.
+In order to test the provider, you can run:
 
 ```console
 make test

diff --git a/mkdocs/generating-documentation.md b/mkdocs/generating-documentation.md
@@ -0,0 +1,20 @@
+# Generating Documentation
+
+This provider uses [terraform-plugin-docs](https://github.com/hashicorp/terraform-plugin-docs/) to generate documentation and store it in the [docs/](https://github.com/bschaatsbergen/terraform-provider-assert/tree/main/docs) directory. Once a release is cut, the Terraform Registry will download the documentation from [docs/](https://github.com/bschaatsbergen/terraform-provider-assert/tree/main/docs) and associate it with the release version. Read more about how this works on the official page.
+
+### Adding documentation for a new function
+
+To add documentation for a new function, you need to do 2 things:
+
+* Add a `<function>.md.tmpl` file in the [templates/](https://github.com/bschaatsbergen/terraform-provider-assert/tree/main/templates) directory. This file is used by [terraform-plugin-docs](https://github.com/hashicorp/terraform-plugin-docs/) to generate the documentation. You can refer to one of the existing files to create a new one.
+
+* Add examples to the [examples/](https://github.com/bschaatsbergen/terraform-provider-assert/tree/main/examples) directory. These examples are referenced in the template files and are used to generate the examples section in the documentation. We recommend adding an example for Terraform Test and Variable Validation. You can refer to one of the existing examples to create a new one.
+
+
+### Generating documentation
+
+After adding a new function to the [templates/](https://github.com/bschaatsbergen/terraform-provider-assert/tree/main/templates) and [examples/](https://github.com/bschaatsbergen/terraform-provider-assert/tree/main/examples) directories, run:
+
+```sh
+make generate
+```
diff --git a/mkdocs/releasing.md b/mkdocs/releasing.md
@@ -0,0 +1,6 @@
+# Releasing
+
+The release process is automated via GitHub Actions, and defined in the Workflow [release.yml](https://github.com/bschaatsbergen/terraform-provider-assert/blob/main/.github/workflows/release.yml).
+
+Each release is cut by pushing a [semantically versioned](https://semver.org/) tag to the default branch.
+
diff --git a/mkdocs/testing.md b/mkdocs/testing.md
@@ -0,0 +1,11 @@
+# Testing
+
+In order to test the provider, you can run:
+
+```console
+make test
+```
+
+### Writing function tests
+
+All functions should have corresponding tests. See the [write passing tests](./add-a-new-function.md#write-passing-tests) section for more information.
diff --git a/mkdocs/usage.md b/mkdocs/usage.md