Migrate to Terraform Plugin Framework

.changes/unreleased/NOTES-20230227-115045.yaml

@@ -0,0 +1,5 @@
+kind: NOTES
+body: 'provider: Rewritten to use the [`terraform-plugin-framework`](https://www.terraform.io/plugin/framework)'
+time: 2023-02-27T11:50:45.423274-05:00
+custom:
+  Issue: "184"

.github/CODE_OF_CONDUCT.md

@@ -0,0 +1,5 @@
+# Code of Conduct
+
+HashiCorp Community Guidelines apply to you when interacting with the community here on GitHub and contributing code.
+
+Please read the full text at https://www.hashicorp.com/community-guidelines

.github/SUPPORT.md

@@ -1,5 +1,6 @@
 # Support
 
-Terraform is a mature project with a growing community. There are active, dedicated people willing to help you through various mediums.
-
-Take a look at those mediums listed at https://www.terraform.io/community.html
+* Project [README](../README.md)
+* Official [Documentation](https://registry.terraform.io/providers/hashicorp/external/latest/docs)
+* Providers [Discuss forums](https://discuss.hashicorp.com/c/terraform-providers/31)
+* Terraform [Community](https://www.terraform.io/community.html) page

.github/workflows/test.yml

@@ -1,4 +1,5 @@
-name: Tests
+name: Test
+
 on:
   pull_request:
     branches: [ main ]
@@ -12,64 +13,76 @@ on:
       - 'README.md'
       - 'CHANGELOG.md'
       - 'website/*'
+
 jobs:
+
   build:
     name: Build
     runs-on: ubuntu-latest
     timeout-minutes: 5
+
+    strategy:
+      matrix:
+        go-version: [ '1.18' ]
+
     steps:
-    - uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3.3.0
-    - name: Set up Go
-      uses: actions/setup-go@6edd4406fa81c3da01a34fa6f6343087c207a568 # v3.5.0
-      with:
-        go-version-file: 'go.mod'
-      id: go
 
-    - name: Go fmt
-      run: |
-        make fmt
+      - uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3.3.0
+      - uses: actions/setup-go@6edd4406fa81c3da01a34fa6f6343087c207a568 # v3.5.0
+        with:
+          go-version: ${{ matrix.go-version }}
+
+      - name: Run linters
+        uses: golangci/golangci-lint-action@08e2f20817b15149a52b5b3ebe7de50aff2ba8c5 # v3.4.0
+        with:
+          version: latest
 
-    - name: Go vet
-      run: |
-        make vet
+      - name: Generate
+        run: make generate
 
-    - name: Build
-      run: |
-        go build -v .
+      - name: Confirm no diff
+        run: |
+          git diff --compact-summary --exit-code || \
+            (echo "*** Unexpected differences after code generation. Run 'make generate' and commit."; exit 1)
 
+      - name: Build
+        run: make build
 
-# run acceptance tests in a matrix with Terraform core versions
   test:
-    name: Matrix Test
+    name: 'Acc. Tests (OS: ${{ matrix.os }} / TF: ${{ matrix.terraform }})'
     needs: build
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.os }}
     timeout-minutes: 15
+
     strategy:
       fail-fast: false
       matrix:
+        os:
+          - macos-latest
+          - ubuntu-latest
         terraform:
           - '0.12.*'
           - '0.13.*'
           - '0.14.*'
           - '0.15.*'
           - '1.0.*'
           - '1.1.*'
+          - '1.2.*'
+          - '1.3.*'
+
     steps:
-    - uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3.3.0
-    - name: Set up Go
-      uses: actions/setup-go@6edd4406fa81c3da01a34fa6f6343087c207a568 # v3.5.0
-      with:
-        go-version-file: 'go.mod'
-      id: go
-    - uses: hashicorp/setup-terraform@633666f66e0061ca3b725c73b2ec20cd13a8fdd1 # v2.0.3
-      with:
-        terraform_version: ${{ matrix.terraform }}
-        terraform_wrapper: false
-    # See also: https://github.com/hashicorp/setup-terraform/issues/143
-    - run: terraform version
-    - run: go mod download
-    - name: TF acceptance tests
-      timeout-minutes: 10
-      env:
-        TF_ACC: "1"
-      run: go test -v -cover ./internal/provider/
+
+      - uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3.3.0
+      - uses: actions/setup-go@6edd4406fa81c3da01a34fa6f6343087c207a568 # v3.5.0
+        with:
+          go-version-file: 'go.mod'
+
+      - name: Setup Terraform ${{ matrix.terraform }}
+        uses: hashicorp/setup-terraform@633666f66e0061ca3b725c73b2ec20cd13a8fdd1 # v2.0.3
+        with:
+          terraform_version: ${{ matrix.terraform }}
+          terraform_wrapper: false
+
+      - name: Run acceptance test
+        run: make testacc
+

.golangci.yml

@@ -0,0 +1,26 @@
+
+issues:
+  max-per-linter: 0
+  max-same-issues: 0
+
+linters:
+  disable-all: true
+  enable:
+    - durationcheck
+    - errcheck
+    - exportloopref
+    - forcetypeassert
+    - godot
+    - gofmt
+    - gosimple
+    - ineffassign
+    - makezero
+    - misspell
+    - nilerr
+    - predeclared
+    - staticcheck
+    - tenv
+    - unconvert
+    - unparam
+    - unused
+    - vet

DESIGN.md

@@ -0,0 +1,34 @@
+# External Provider Design
+
+ The External Provider allows external programs to interact with Terraform by implementing a specific protocol. 
+
+Below we have a collection of _Goals_ and _Patterns_: they represent the guiding principles applied during the
+development of this provider. Some are in place, others are ongoing processes, others are still just inspirational.
+
+## Goals
+
+* [_Stability over features_](.github/CONTRIBUTING.md)
+* Provide an "escape hatch" for external programs to interact with Terraform in exceptional situations where a first-class Terraform provider is not more appropriate.
+  * This provider is **not** intended to work with any external program with no modifications, but for small "glue" programs tailored to work with Terraform.
+* Define a protocol for external programs to implement in order to communicate with Terraform through the provider.
+* Provide comprehensive documentation 
+* Highlight intended and unadvisable usages
+
+## Patterns
+
+Specific to this provider:
+
+* The data source protocol uses JSON objects to communicate between the provider and the external program.
+
+General to development:
+
+* **Avoid repetition**: the entities managed can sometimes require similar pieces of logic and/or schema to be realised.
+  When this happens it's important to keep the code shared in communal sections, so to avoid having to modify code in
+  multiple places when they start changing.
+* **Test expectations as well as bugs**: While it's typical to write tests to exercise a new functionality, it's key to
+  also provide tests for issues that get identified and fixed, so to prove resolution as well as avoid regression.
+* **Automate boring tasks**: Processes that are manual, repetitive and can be automated, should be. In addition to be a
+  time-saving practice, this ensures consistency and reduces human error (ex. static code analysis).
+* **Semantic versioning**: Adhering to HashiCorp's own
+  [Versioning Specification](https://www.terraform.io/plugin/sdkv2/best-practices/versioning#versioning-specification)
+  ensures we provide a consistent practitioner experience, and a clear process to deprecation and decommission.

GNUmakefile

@@ -1,45 +1,25 @@
-TEST?=$$(go list ./...)
-GOFMT_FILES?=$$(find . -name '*.go')
-PKG_NAME=external
-
 default: build
 
-build: fmtcheck
-	go install
+build:
+	go build -v ./...
 
-test: fmtcheck
-	go test -i $(TEST) || exit 1
-	echo $(TEST) | \
-		xargs -t -n4 go test $(TESTARGS) -timeout=30s -parallel=4
+install: build
+	go install -v ./...
 
-testacc: fmtcheck
-	TF_ACC=1 go test $(TEST) -v $(TESTARGS) -timeout 120m
+# See https://golangci-lint.run/
+lint:
+	golangci-lint run
 
-vet:
-	@echo "go vet ."
-	@go vet $$(go list ./...) ; if [ $$? -eq 1 ]; then \
-		echo ""; \
-		echo "Vet found suspicious constructs. Please check the reported constructs"; \
-		echo "and fix them if necessary before submitting the code for review."; \
-		exit 1; \
-	fi
+generate:
+	go generate ./...
 
 fmt:
-	gofmt -w $(GOFMT_FILES)
-
-fmtcheck:
-	@sh -c "'$(CURDIR)/scripts/gofmtcheck.sh'"
-
-errcheck:
-	@sh -c "'$(CURDIR)/scripts/errcheck.sh'"
+	gofmt -s -w -e .
 
+test:
+	go test -v -cover -timeout=120s -parallel=4 ./...
 
-test-compile:
-	@if [ "$(TEST)" = "./..." ]; then \
-		echo "ERROR: Set TEST to a specific package. For example,"; \
-		echo "  make test-compile TEST=./$(PKG_NAME)"; \
-		exit 1; \
-	fi
-	go test -c $(TEST) $(TESTARGS)
+testacc:
+	TF_ACC=1 go test -v -cover -timeout 120m ./...
 
-.PHONY: build test testacc vet fmt fmtcheck errcheck test-compile
+.PHONY: build install lint generate fmt test testacc