This document describes how to contribute to Kitchen-Terraform. Proposals for changes to this document are welcome.
Contributors to Kitchen-Terraform are expected to adhere to the Kitchen-Terraform Code of Conduct. Any unacceptable conduct should be reported to kitchen-terraform@newcontext.com.
Questions about the project may be posed on the GitHub issue tracker or in the Gitter chat.
Familiarity with the following technologies is important in understanding the design and behaviour of Kitchen-Terraform.
Bugs must be reported on the GitHub issue tracker. Any information that will assist in the maintainers reproducing the bug should be included.
Changes should be suggested on the GitHub issue tracker. Submitting a pull request with an implementation of the changes is also encouraged but not required.
The development workflow for both the Kitchen-Terraform Ruby gem and the documentation web site follow the same standard GitHub workflow.
RSpec is used as the unit testing framework.
Rake is used to orchestrate the unit tests.
The following command will execute the unit tests.
Executing unit tests with RSpec
bundle exec rake test:rspec.rspec contains command line options which will be automatically applied.
spec/spec_helper.rb contains framework configuration.
The files under spec/lib contain the executable descriptions of the different units of the Ruby gem.
The files under spec/support contain supporting logic like shared examples and shared contexts.
Guard can be used to automate the execution of unit tests during the development process.
The following command will start the process to detect file changes and run appropriate unit tests.
Watching for file changes with Guard
bundle exec guardKitchen, Terraform, and InSpec are used as the integration testing framework.
Rake is used to orchestrate the integration tests.
The following command will execute the integration tests.
Executing integration tests with Rake
bundle exec rake test:kitchen:allRakefile contains the task definitions.
The Terraform Docker provider is used to run integration tests against a real Terraform state.
integration/basic includes Kitchen-Terraform configuration and an InSpec profile used to verify the basic features of Kitchen-Terraform.
Other directories under integration are used to test the handling of special cases.
Code Climate is used to analyze the quality of the source code of the Ruby gem.
.codeclimate.yml contains analysis configuration.
A command line interface is available to run the analysis locally.
GitHub Actions are used to provide continuous integration and continuous deployment functionality for the Ruby gem.
rspec-tests.yml defines unit tests that will be executed for each commit to the master branch and each commit to a branch with an open pull request.
kitchen-tests.yml defines integration tests that will be executed for each commit to the master branch and each commit to a branch with an open pull request.
release.yml contains the job configuration to deploy the Ruby gem. If a tag starting with v is pushed to the master branch, then the job will attempt to build the Ruby gem and deploy it to RubyGems.
Changes will be committed to the master branch as they are completed. When the goals of the next project milestone have been achieved, the master branch will be tagged with a new version number which will trigger a release of the Ruby gem.
The web site comprises documentation, examples, and tutorials for working with Kitchen-Terraform.
The web site published on the master branch is hosted at https://newcontext-oss.github.io/kitchen-terraform/.
The web site uses the Middleman framework.
The following command will run the Middleman server so that changes to the content can be reviewed at http://localhost:4567/.
Running Middleman server to review content changes
env NO_CONTRACTS=true bundle exec middleman server --build-dir docsconfig.rb contains Middleman configuration.
source contains the source files for the web site.
docs contains the compiled web site.
The following command will build an HTML site based on the Middleman project.
Building HTML site based on Middleman project
bundle exec middleman build --build-dir docs