Contributions like bug fixes and enhancements may be submitted through Pull Requests on this repository. Before we can accept 3rd-party pull requests, you will first need to sign and submit the Contribution Agreement. Please make sure to mention your GitHub username when submitting the form, to allow us to verify that the author of a pull request has accepted this agreement.
After cloning this repository, please run ./configure.sh to install npm modules and configure git hooks. When adding a new NodeJS-based action, you'll need to update <repo-root>/configure.sh to add the action directory to the for-loop.
To potentially support multiple versions of the tool definitions (to cater for changes in tool definition yaml file structure), tool definitions are published to the v1 directory in this repository, allowing us to add a v2 directory for example if necessary. This allows us to generate both v1 and v2 tool definition files; older clients may still use the v1 tool definitions whereas newer clients may use the v2 tool definitions.
Doing this through regular GitHub tags/releases would be much more difficult, as on every run we'd potentially need to generate multiple tags/releases, like a v1 tag pointing to v1.5.0 and a v2 tag pointing to v2.1.0, each with different sets of files.
Regular semantic versioning principles apply; as long as the generated files are backward-compatible, the files can be stored in the v1 directory. If necessary, we can add new properties to the output files or add new output files (to support additional tools), but we cannot rename or remove existing output files, or change the structure of existing output files. For example, we cannot rename or remove existing properties, or change the structure of existing property values (like changing from base64 encoding to a different encoding). If any such non-backwardcompatible changes are necessary, we should add a new v2 directory and update the internal/generator action (see below) to generate both the legacy v1 output and a new v2 output.
The .github/workflows/publish.yml GitHub workflow is responsible for generating the tool definition files. Information about which GitHub repositories/releases/assets to process is defined in this GitHub workflow, together with information as to how for example determine artifact type from artifact download URL.
This GitHub workflow runs automatically on every push and on a daily schedule, to make sure tool definitions are updated every day. If necessary, for example to expedite tool definition updates once a new version of any of the tools is released, the workflow can also be triggered manually.
Information about each tool is defined in a matrix in the setup job, the generate-tool-definitions job takes this matrix as input to generate the tool definitions file for each tool defined in the matrix. Once all tool definition files have been generated, the generate-tool-definitions-zip creates a zip-file containing the individual tool definition files.
The generate-tool-definitions job utilizes the internal/generator Node.js-based action to actually generate the tool definition files; see below for more information. Any new/updated files generated by the generate-tool-definitions and generate-tool-definitions-zip jobs are automatically committed back to the repository. As such, please make sure to run a git pull before manually committing any changes to this repository.
The internal/generator Node.js-based action is responsible for actually generating the tool definition files, based on action inputs that for example define tool name, tool repository (or static list of tool versions and download URLs), and regular expressions used to determine what tool versions and assets to include in the tool definition files. This action consists of the following source files:
constants.ts: Defines global constants for use by the other modules; most of the constants are based on GitHub Action inputs.descriptor.ts: Defines various 'descriptor' classes that hold information about tool versions and artifacts, together with various utility methods for working with these versions and artifacts.loader.ts: Responsible for loading information about tool versions and artifacts, for example by iterating over all releases and the assets for each of these releases for a given tool GitHub repository.main.ts: Main entry point for this GitHub Action, usingloader.tsto load version and artifact data, andwriter-v1.tsto write thev1tool definition files.writer-v1.ts: Responsible for writingv1tool definition files.
See action.yml
Some of the information in the tool definition files is relatively expensive to calculate. For example, tool artifacts must be downloaded in order to calculate file digests and signatures. As such, the internal/generator action caches this information in the internal/cache directory in files named <tool name>/<tool version>-<artifact file name from download URL>.json. Just like the tool definition files themselves, any new/updated cache files are automatically committed to the repository by the GitHub workflow.
In general, the action assumes that cached data doesn't change, i.e., once cached, the action will use the cached data and not attempt to re-download the tool artifact to verify whether digests/signatures are still correct. The only exception is for GitHub releases marked as 'pre-release' or if the semantic version contains a pre-release label like 1.0.0-beta1. This has the following implications:
- If for any reason the cached information for non-prerelease artifacts is incorrect, the corresponding cache file needs to be manually removed in order for the action to regenerate the cache entry. Upon the next action run, the cache entry will be regenerated.
- For pre-releases, the action will download the artifacts and recalculate digests/signatures on every run.
This document was auto-generated from CONTRIBUTING.template.md; do not edit by hand