GitHub Workflow for automated testing

.github/workflows/checks.yaml

@@ -0,0 +1,46 @@
+name: Terraform Provider ACI Checks
+
+on:
+  pull_request:
+    paths:
+      - '.github/workflows/checks.yaml'
+      - '**.go'
+
+permissions:
+  # Permission for checking out code
+  contents: read
+
+jobs:
+  build:
+    name: Build Checks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-go@v4
+        with:
+          go-version-file: 'go.mod'
+      - run: chmod +x ./scripts/gofmtcheck.sh
+      - name: gofmt Check
+        run: ./scripts/gofmtcheck.sh
+      - name: Build
+        run: go build -v
+  acceptance:
+    name: Acceptance Tests
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-go@v4
+        with:
+          go-version-file: 'go.mod'
+      - uses: hashicorp/setup-terraform@v2
+        with:
+          terraform_version: '1.5.*'
+          terraform_wrapper: false
+      - run: go test github.com/CiscoDevNet/terraform-provider-aci/v2/internal/provider -v -cover -timeout 120m
+        env:
+          TF_ACC: '1'
+          TF_ACC_STATE_LINEAGE: '1'
+          ACI_USERNAME: ${{ secrets.TF_ACC_ACI_USERNAME }}
+          ACI_PASSWORD: ${{ secrets.TF_ACC_ACI_PASSWORD }}
+          ACI_URL: ${{ secrets.TF_ACC_ACI_URL }}

README.md

@@ -1,15 +1,15 @@
 # Cisco ACI Provider
 
-Requirements
-------------
+## Requirements
 
 - [Terraform](https://www.terraform.io/downloads.html) 
   - v0.12 and higher (ACI Provider v1.0.0 or higher)
   - v0.11.x or below (ACI Provider v0.7.1 or below)
 
 - [Go](https://golang.org/doc/install) Latest Version
 
-## Building The Provider ##
+## Building The Provider
+
 Clone this repository to: `$GOPATH/src/github.com/CiscoDevNet/terraform-provider-cisco-aci`.
 
 ```sh
@@ -26,9 +26,8 @@ $ make build
 
 ```
 
-Using The Provider
-<!-- https://www.terraform.io/docs/plugins/basics.html#installing-a-plugin -->
-------------------
+## Using The Provider
+
 If you are building the provider, follow the instructions to [install it as a plugin.](https://www.terraform.io/docs/cli/plugins/index.html) After placing it into your plugins directory, run `terraform init` to initialize it.
 
 ex.
@@ -88,9 +87,124 @@ terraform apply -parallelism=1
 
 Note: The value of "cert_name" argument must match the name of the certificate object attached to the APIC user (aaaUserCert) used for signature-based authentication
 
-Developing The Provider
------------------------
-If you want to work on the provider, you'll first need [Go](http://www.golang.org) installed on your machine. 
+## Developing The Provider
+
+Currently the ACI provider is a [muxed provider](https://developer.hashicorp.com/terraform/plugin/mux) which allows us to simultaneously serve [terraform-plugin-sdk/v2](https://developer.hashicorp.com/terraform/plugin/sdkv2) and [terraform-plugin-framework](https://developer.hashicorp.com/terraform/plugin/framework) provider SDK implementations. This adds some complexity to the development process, but allows us to leverage the new capabilities that terraform-plugin-framework provides, while working on a migration strategy for existing resources.
+
+### Pre-Requirements
+
+1. Install latest version of [Go](http://www.golang.org)
+
+### Existing resources and data-sources developed with terraform-plugin-sdk/v2
+
+* Existing resources and data-sources are located in the [aci](https://github.com/CiscoDevNet/terraform-provider-aci/tree/master/aci) directory.
+
+* Changes are made directly in the `provider.go`, `resource_*.go`, `data_source_*.go` and `utils` files. The [aci-go-client](https://github.com/ciscoecosystem/aci-go-client) is leveraged to construct payload constructs and handle REST communication towards the APIC.
+
+* Documentation is manually maintained in the [legacy-docs](https://github.com/CiscoDevNet/terraform-provider-aci/tree/master/legacy-docs) directory and are copied automatically up on execution of `go generate` command.
+
+* Examples are manually maintained in the [examples](https://github.com/CiscoDevNet/terraform-provider-aci/tree/master/examples) directory, where each resource has it's own directory.
+
+#### Manual Development Process
+
+The below steps should be followed for developing `terraform-plugin-sdk/v2` resources and data-sources:
+
+1. Create issue (if not created yet) and comment that you will be working on the issue.
+
+2. Fork the terraform-provider-aci repository.
+
+3. Clone the forked code to your local machine.
+
+4. Make changes to the files manually.
+    * Code changes
+    * Examples changes
+    * Documentation changes 
+
+5. Run `go generate` in the root of the local repository where the `main.go` is located. Assure that the documentation is copied to the docs folder and no changes are made to files in the [internal/provider](https://github.com/CiscoDevNet/terraform-provider-aci/tree/master/internal/provider) directory.
+
+5. Test the code.
+
+6. Create PR for the code and request review from active maintainers.
+
+7. Review process
+
+### New resources and data-sources developed with terraform-plugin-framework
+
+* New resources and data-sources are located in the [internal/provider](https://github.com/CiscoDevNet/terraform-provider-aci/tree/master/internal/provider) directory.
+
+* The `provider.go`, `resource_*.go`, `resource_*_test.go`, `data_source_*.go`, `data_source_*_test.go` are generated with templates and should not be changed manually. Files that are automatically generated start with `// Code generated by "gen/generator.go"; DO NOT EDIT.` and should not be modified. When a file is not generated correctly, the template of that file must be adjusted.
+
+* Examples used in the documentation are generated automatically and stored in the [examples/resources](https://github.com/CiscoDevNet/terraform-provider-aci/tree/master/examples/resources) and [examples/data-sources](https://github.com/CiscoDevNet/terraform-provider-aci/tree/master/examples/data-sources) directories.
+
+* Documentation for resources and datasources are generated automatically and stored in the [docs](https://github.com/CiscoDevNet/terraform-provider-aci/tree/master/docs) directory.
+
+* There are a few exceptions of static files which need to be changed manually:
+
+  * Files related to `rest_managed`
+  * [provider_test.go](https://github.com/CiscoDevNet/terraform-provider-aci/tree/master/internal/provider/provider_test.go)
+  * [provider.tf](https://github.com/CiscoDevNet/terraform-provider-aci/tree/master/examples/provider/provider.tf)
+
+#### Generator Process
+
+New resources and data-sources are generated with [generator.go](https://github.com/CiscoDevNet/terraform-provider-aci/tree/master/examples/gen/generator.go). The generator assumes that the following directories exist in the directory where the generate.go file is located:
+
+- `./definitions`
+  * contains the manually created YAML files with the ACI class definitions for overwriting the meta data retrieved from APIC
+
+- `./meta`
+  * contains the JSON files with the ACI class metadata which are retrieved from APIC
+
+- `./templates`
+  * contains the Go templates used to generate the full provider code
+
+- `./testvars`
+  * contains the generated YAML files with the test variables used in the *_test.go and example files
+
+The below steps should be followed for developing `terraform-plugin-framework` resources and data-sources:
+
+1. Create issue and comment that you will be working on the issue.
+
+2. Fork the terraform-provider-aci repository.
+
+3. Clone the forked code to your local machine.
+
+4. Add minimum required class details to [classes.yaml](https://github.com/CiscoDevNet/terraform-provider-aci/tree/master/examples/gen/definitions/classes.yaml).
+  * `ui_location`
+  * `sub_category`
+  * `tagAnnotation` is added to children when this is allowed to be configure under the class 
+
+5. Copy new meta file(s) or replace existing with newer version of the meta file(s) to the [meta](https://github.com/CiscoDevNet/terraform-provider-aci/tree/master/examples/gen/meta) directory in the following format: `<classname>.json`. Assure that all relationship classes are also added to the `meta` directory. The `GEN_HOST` and `GEN_CLASSES` environment variables can be leveraged to retrieve the classes automatically before rendering the code.
+  * `GEN_HOST` should be set to a resolvable host, example: `173.36.219.70`
+  * `GEN_CLASSES` should be set to a comma-separated string of classes, example: `fvTenant` or `fvTenant,fvBD`
+
+6. Run `go generate` in the root of the local repository where the `main.go` is located. The following files should be created or updated:
+  * `resource_<resource-name>.go` and `resource_<resource-name>_test.go`
+  * `data_source_<resource-name>.go` and `data_source_<resource-name>_test.go`
+  * `<resource-name>.md` in the [docs/resources](https://github.com/CiscoDevNet/terraform-provider-aci/tree/master/docs/resources) and [docs/data-sources](https://github.com/CiscoDevNet/terraform-provider-aci/tree/master/docs/data-sources) directories.
+  * `resource.tf` and `data-source.tf`
+  * `provider.go`
+
+6. Validate generated files generated on the following items:
+  * resource name
+    * incorrect resource names should be overwritten in [classes.yaml](https://github.com/CiscoDevNet/terraform-provider-aci/tree/master/examples/gen/definitions/classes.yaml) by providing `resource_name: "<resource-name>"`
+  * schema attributes ( class properties and children )
+    * incorrect property names should be overwritten in [properties.yaml](https://github.com/CiscoDevNet/terraform-provider-aci/tree/master/examples/gen/definitions/properties.yaml) by providing a global or class specific overwrite
+    * all relationships classes are included
+  * documentation contains the example and all information is correct
+  * Run `go generate` again until the files are generated as preferred. When you are not achieving the desired outputs, reource, data-source, example and/or documentation templates should be adjusted.
+
+8. Test the generated code of your resources and dat-sources
+  * Execute the tests for all your generated resources and data-sources
+  * The following command can be used `go test internal/provider/* -v -run <test-name>`, where the test name can be found in the `resource_<resource-name>_test.go` and `data_source_<resource-name>_test.go` files.
+  * Adjust generated test_values in case incorrect values are used. All test values are resolved by estimating the values. Some values are hard to resolve with and thus need to be overwritten in [properties.yaml](https://github.com/CiscoDevNet/terraform-provider-aci/tree/master/examples/gen/definitions/properties.yaml) file under the class specific test_values.
+  * Some tests have a dependency on a specific parent, which is unknown because the resource is not an autogenerated resource yet. This can be set in the [properties.yaml](https://github.com/CiscoDevNet/terraform-provider-aci/tree/master/examples/gen/definitions/properties.yaml) file under the the class specific parents.
+  * Run `go generate` again until the files are generated as preferred. When you are not achieving the desired outputs, the test templates should be adjusted.
+
+9. Create PR for the code and request review from active maintainers.
+
+10. Review process
+
+### Compiling
 
 To compile the provider, run `make build`. This will build the provider with sanity checks present in scripts directory and put the provider binary in `$GOPATH/bin` directory.
 
@@ -115,3 +229,5 @@ To compile the provider, run `make build`. This will build the provider with san
   ```
 
 <strong>NOTE:</strong> Currently only resource properties supports the reflecting manual changes made in CISCO ACI. Manual changes to relationship is not taken care by the provider.
+
+