Skip to content

Latest commit

 

History

History
261 lines (167 loc) · 11.3 KB

CONTRIBUTING.md

File metadata and controls

261 lines (167 loc) · 11.3 KB

Provider Development

Contributions are welcome! For most, the best way is to make your changes in a fork, then issue a pull request to have your changes merged back upstream. See Creating a pull request from a fork.

Most development activity requires having a Citrix ITM account with API access enabled. If you're unable to access the OAuth configuration page to create credentials (see below), it most likely means that your account doesn't have the necessary permissions. If that's the case, please send an email to Citrix ITM Support to request access to the API.

Compiling

To compile the provider run make build from within the project root directory:

$ make build
==> Checking that code complies with gofmt requirements...
go install

This should place a binary file named terraform-provider-citrixitm within $GOPATH/bin. If you plan on actually using it with Terraform, you should copy that file into ~/.terraform.d/plugins/ at this point.

Testing

An important part of provider development is testing. There are two types of tests:

Unit Tests

Unit tests are for testing small parts of the code base isolated from any interaction with the Citrix ITM API. Run make test from within the project root directory:

$ make test
==> Checking that code complies with gofmt requirements...
go test -i $(go list ./... |grep -v 'vendor') || exit 1
echo $(go list ./... |grep -v 'vendor') | \
        xargs -t -n4 go test  -timeout=30s -parallel=4
go test -timeout=30s -parallel=4 github.com/cedexis/terraform-provider-citrixitm github.com/cedexis/terraform-provider-citrixitm/citrixitm
?       github.com/cedexis/terraform-provider-citrixitm [no test files]
ok      github.com/cedexis/terraform-provider-citrixitm/citrixitm       0.015s

Acceptance Tests

Acceptance tests invoke a test harness to exercise the code in the same way that Terraform does. This is vital to ensuring that the provider will work as expected in production.

Before running the acceptance test suite, you should make sure to set the following environment variables:

  • ITM_CLIENT_ID - An OAuth client ID

    You can set this up on the Citrix ITM Portal OAuth Config page.

  • ITM_CLIENT_SECRET - The client secret corresponding to that client ID.

To run the acceptance test suite, execute make testacc from within the project root directory:

$ make testacc
==> Checking that code complies with gofmt requirements...
?       github.com/cedexis/terraform-provider-citrixitm [no test files]
=== RUN   TestConfig
2018/09/12 23:01:46 [DEBUG] Checking URL for trailing slash: http://foo.com/api
--- PASS: TestConfig (0.00s)
=== RUN   TestProvider
--- PASS: TestProvider (0.00s)
=== RUN   TestProvider_impl
--- PASS: TestProvider_impl (0.00s)
=== RUN   TestAccDnsApp_basic
--- PASS: TestAccDnsApp_basic (11.52s)
PASS
ok      github.com/cedexis/terraform-provider-citrixitm/citrixitm       (cached)

For more information about Terraform acceptance testing, please read Extending Terraform - Acceptance Testing.

Best Practices

Terraform log output

As a debugging best practice, Hashicorp would like every C/R/U/D operation to output at minimum two [INFO] log entries, e.g. [INFO] Creating..., [INFO] Created.... To clarify things further, we'll standardize on the following logging requirements for every resource type:

For the CREATE operation, output the following:

  • Before actually creating the resource:
[INFO] Creating <resource name>
  • Before actually creating the resource:
[DEBUG] <resource name> create options:
...
  • After creating the resource:
[INFO] Created <resource name> with ID <resource ID>

For the READ operation, output the following:

  • Before actually reading the resource:
[INFO] Reading <resource name>
  • After actually reading the resource:
[INFO] Read <resource name> with ID <resource ID>

For the UPDATE operation, output the following:

  • Before actually updating the resource:
[INFO] Updating <resource name>
  • Before actually updating the resource:
[DEBUG] <resource name> update options:
...
  • After updating the resource:
[INFO] Updated <resource name> with ID <resource ID>

For the DELETE operation, output the following:

  • Before actually deleting the resource:
[INFO] Deleting <resource name> with ID <resource ID>
  • After deleting the resource:
[INFO] Deleted <resource name> with ID <resource ID>

Website Documentation

A community Terraform provider must include all of the documentation to be hosted on the main Terraform website (see https://www.terraform.io/docs/providers/). These are static pages generated by Middleman from source code found at https://github.com/hashicorp/terraform-website. Rather than updating that repository directly, symlinks are created within it pointing to resources in each community provider repository. These symlinks are discussed more below.

Setup

The following guidelines assume a UNIX environment and a Bash shell.

GOPATH is out, go.mod is in

Since Go 1.11, go mod is used to handle dependencies. A project now specifies the external packages it uses, as well as their versions, in its go.mod file, and the Go tools handle the rest. There's no longer a need to bundle versioned dependecies in a vendor directory.

Go also no longer expects to find local packages within $GOPATH, and you no longer have to put the code you're working on there either. In other words, you can clone git@github.com:cedexis/terraform-provider-citrixitm.git anywhere you choose, rather than its having to be located within $GOPATH.

Docker

Everything needed to build the website is containerized using Docker, so you'll need to have Docker installed. Instructions vary by platform.

Debian

See https://docs.docker.com/install/linux/docker-ce/debian/.

Be sure to add your user to the docker group. Otherwise you may encounter permissions issues connecting to the Docker daemon.

sudo usermod -a -G docker $USER

After adding the user to the docker group, you'll need to log out and spawn a new session.

Create terraform-website repo symlinks

Note: Only needed until the Citrix ITM provider is accepted as a community provider. At that time, the symlinks will be added to the official terraform-website repo and this section can be deleted.

The terraform-website repo contains the source code for a static website generated by Middleman.

Clone the terraform-website repo to the expected location:

$ mkdir -p $GOPATH/src/github.com/hashicorp
$ git clone https://github.com/hashicorp/terraform-website $GOPATH/src/github.com/hashicorp/terraform-website

Two symlinks are needed in order for Middleman to find the website code in the terraform-provider-citrixitm repo.

$ cd $GOPATH/src/github.com/hashicorp/terraform-website/content/source/layouts
$ ln -s ../../../ext/providers/citrixitm/website/citrixitm.erb
$ cd $GOPATH/src/github.com/hashicorp/terraform-website/content/source/docs/providers
$ ln -s ../../../../ext/providers/citrixitm/website/docs citrixitm

From outside of the Docker container these symlinks will appear broken, but they work inside the container because Docker mounts the directories that they point to based on the Make target used to create the container.

Documentation Development Guidelines

When Hashicorp builds the Terraform website, sources are pulled from the stable-website branch of each community provider repo. You should only modify this branch when material changes have been made to the documentation and are ready to be published. Documentation source changes should accumulate in master and only be merged to stable-website when thoroughly reviewed for acceptance by team members.

Please use the following basic guidelines:

  1. Create pull requests to merge from master to stable-website.

    This insures that team members get a chance to review documentation changes before they are published to terraform.io.

    Documentation changes can accumulate in master and be merged to stable-website together under a single pull request. This allows documentation to be updated continuously without having to go through the full review process.

    Collaborators may want to work out a system to facilitate creating this pull request on a somewhat regular basis so that stable-website doesn't fall too far behind master.

  2. Always merge from master to stable-website, never the other way around.

    If any changes exist in stable-website that don't exist in master, it likely means that someone made a commit directly to stable-website without going through the PR process. Please don't do this.

  3. Making documentation source changes alongside relevant Go changes is nice.

    If you're working on a new feature of the Terraform provider it's helpful, although not strictly necessary, for documentation changes to be included under the same pull request for merging your feature branch into master.

  4. Making documentation-only source changes is fine.

    You may just want to make changes to the documentation source, not in conjunction with any specific change to the Go code. This is absolutely fine. We want the documentation to be as good as it can possibly be, so documentation-only changes are welcome. Please use the following workflow:

    1. Create a feature branch based on master.
    2. Make documentation source changes on the feature branch.
    3. Submit a pull request to merge the feature branch into master.

Running Middleman Locally

Working on the documentation locally involves running Middleman to generate the site, which can be viewed in a browser at http://localhost:4567. The source files for the provider documentation are found in this repository under the website directory. Middleman watches for changes and rebuilds the site as you edit these files. With LiveReload the browser should show the effect of changes immediately.

To get started, kick off Middleman in development mode. From the root directory of the provider project:

$ make website

This starts Middleman as a long running process in a new Docker container.

You should now be able to view the provider documentation, exactly as it would appear when hosted on terraform.io, by pointing your browser at http://localhost:4567/docs/providers/citrixitm.

Press Ctrl+C to shutdown and remove the Docker container.

You can also run the documenation acceptance tests, which basically just check for the presence of certain expected HTTP resources. From the root directory of the provider project:

$ make website-test

Toward the end of the output, you should see lines similar to this, indicating that things look okay:

/home/jacob/go/src/github.com/hashicorp/terraform-website/content/scripts/check-links.sh "http://127.0.0.1:4567/docs/providers/citrixitm/"
2018-09-05 16:15:12 URL:http://127.0.0.1:4567/docs/providers/citrixitm/ [23358/23358] -> "index.html.tmp.tmp" [1]
2018-09-05 16:15:12 URL:http://127.0.0.1:4567/robots.txt [44/44] -> "robots.txt.tmp" [1]
2018-09-05 16:15:12 URL:http://127.0.0.1:4567/docs/providers/citrixitm/index.html [23358/23358] -> "index.html.tmp.tmp" [1]
Found no broken links.