Contributing Guide

November 17, 2021 · View on GitHub

Repository Structure

Repository Component	Description
`README.md`	Repository overview, displays on GitHub.
`docs/index.md`	Repository overview, gets compiled as the landing page for the documentation
`docs`	Documentation not specific to a particular library, and assets for library docs
`libraries`	The base directory where the libraries are stored

Library Structure

Within the libraries directory, there are several components to be aware of:

Component	Description
`README.md`	The library's documentation page
`steps`	The steps contributed by the library
`resources`	Any reusable content for consumption by the library
`src`	The classes contributed by the library
`test`	The tests for the library

For example, the current repository's a11y library:

libraries/a11y
├── README.md
├── resources
├── src
├── steps
    └── accessibility_compliance_test.groovy
├── test
    └── AccessibilityComplianceTestSpec.groovy

Required Tools

Tool	Purpose
Gradle	Used to run unit tests
Just	A task runner. Used here to automate common commands used during development.
Docker	Used to build the documentation for local preview

Create a Library

Create a new library by running:

just create <library name>

This will produce a folder of the library name with the library structure described above stubbed out. Information for developing a new library can be found on the Create a New Library page.

Documentation

This repository uses Material for MkDocs to build the documentation.

Building the Docs

To build the documentation, run:

just build

This will build the documentation and produce static HTML in the site directory.

Live Reloading

To see changes live as you make them, run:

just serve

The documentation will be accessible at http://localhost:8000.

Testing

Unit tests can be written using Jenkins Spock.

Currently, Gradle 6.3.0 running on JDK 8 is required to run the tests. To see how to install these tools go to Executing Tests.

These tests should go in the test directory for each library.

To run all the tests, run:

just test

The Gradle test report is published to target/reports/tests/test/index.html.

For a specific library

To run tests for a specific library, docker for example, run:

just test '*docker*'

For a specific Specification file

To run tests for a specific Specification file, test/docker/BuildSpec.groovy for example, run:

just test "*.BuildSpec"

Linting

This repository uses npm-groovy-lint with the recommended CodeNarc profile for Jenkins.

The .groovylintrc.json file can be used to tune the rule profile.

To lint the libraries, run:

just lint-code
just lint-docs

The output will go to standard out.

Release Management

This repository automates the creation of release branches and tags as well as publishes the documentation for each version.

Release Automation

To cut a new release, run:

just release $version

Which will:

create a release/$version branch
create a $version tag
publish the documentation for the version and update the latest documentation alias

Automated Changelogs

Release Drafter is used to automate release note updates as Pull Requests are opened to main.

The configuration for Release Drafter exists in the .github/release-drafter.yml file and uses GitHub Actions.