CONTRIBUTING.md

Contributing Guide

This repo leverages the CircleCI orb-tools orb as part of the Orb Development Kit. It provides a full suite of jobs for packing, validating, reviewing, and testing and deploying the orb to the orb registry.

Development

The repo provides a subset of the orb-tools jobs and scripts that can be run locally. It is useful to be able to lint, shellcheck, and review your orbs locally, before committing. With this setup, it is possible to test your code locally, but integration tests of the built orb will be run on CircleCI.

Note: A dev build of the orb will be published as part of the orb-tools/publish job run on every commit. You can use it to test your changes during development. It is also used to do the integration tests as part of the ./.circleci/test-deploy.yml workflow.

Installing CircleCI CLI

The CircleCI command line interface (CLI) brings CircleCI's advanced and powerful tools to your terminal. See Installing the CircleCI local CLI for instructions on how to install it locally on your machine to run the following commands.

Local Packing

All CircleCI orbs are single YAML files, typically named orb.yml. However, for development, it is often easier to break the code up into more manageable chunks. The circleci orb pack command, a component of the orb development kit, is used to "pack" or condense the seprate YAML files together into a single orb.yml file.

circleci orb pack ./src

Local Validating

Once the orb.yml file has been generate via packing you can now validate the configuration using the CircleCI CLI.

circleci orb validate orb.yml

Local Linting

The orb-tools orb-tools/lint job uses a utility yamllint, which can be downloaded and run locally, or you can invoke the job locally with the CircleCI CLI.

Assuming your ./circleci/config.yml file appears similar to the one in this repository, you will have imported the orb-tools orb and defined the orb-tools/lint job in a workflow. Use the Circle CLI from this directory with the following command to locally lint your orb:

CircleCI Local Linting

circleci local execute --job orb-tools/lint

YamlLint Local Linting

yamllint ./src

Local Shellcheck Shellcheck is a static analysis tool for shell scripts, and behaves like a linter for our shell scripts.

CircleCI Local Shellcheck

circleci local execute --job shellcheck/check

Local Review

The review job is a suite of Bash unit tests written using bats-core, a test automation framework for Bash. Each test focuses on checking for a best practice in the orb. The tests can be executed directly with the bats CLI, or you can invoke the job locally with the CircleCI CLI.

CircleCI Local Review

circleci local execute --job orb-tools/review

Note: You will always see a failure at the end of this job when ran locally because the job contains a step to upload test results to CircleCI.com, which is not supported in the local agent.

Commits

Use simple semantic commit convention, just prefix your commits. For example:

major: breaking change
minor: new feature added
fix: a patch release

Releasing

1. Merge changes into master and validate the CI passes all the necessary steps.
2. Create a Github tag of the last commit which merged to master and passed in CI:

   git checkout master
   git pull origin master
   git rev-parse HEA
   # copy sha of the version bump commit
   git tag -s -a vX.Y.Z -m vX.Y.Z <sha>
   git push origin vX.Y.Z

3. Verify the test-deploy workflow passes in CircleCi. This is triggered by pushing the tag to origin which handles releasing the orb changes to https://circleci.com/developer/orbs/orb/cypress-io/cypress.
4. Create a new GitHub release.
   • Choose the tag you created previously.
   • Add the version number to the Release Title and click the Generate release notes button.
   • Check Set as the latest release option.
   • Click the Publish release button.

For an example on how to publish the orb, view the

• CircleCI Orb-Tools Publishing Documentation
• CircleCI Orb-Tools Publishing Params