Skip to content

Latest commit

 

History

History
163 lines (104 loc) · 4.47 KB

index.md

File metadata and controls

163 lines (104 loc) · 4.47 KB
Raw

Contributing Guide

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:

  1. create a release/$version branch
  2. create a $version tag
  3. 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.