CONTRIBUTING.md

Contributing

We recommend to send PRs into official asdf manager.

However when you would add new plugins into this repository from some reasons, this guide might help.

Setup environments

Author is using Nix to maintain this repository. Because of installing crystal via asdf-crystal often make missing lib* packages with depending the PKG_CONFIG.

$ nix develop
(First execution might take long time. Then execute prepared bash with nodejs, crystal and other tools.)
$ make setup
npm install
shards install
shards build
...

Tools

$ ./bin/cli -h
Usage: [arguments]
    -h, --help                       Show this help
    validate                         Validate definitions with renovate provided tool
    lint                             Lint definitions
    scaffold                         Generate files for first step of adding new plugins
    release                          Add git tags in default.json
    touch                            Update renovate.json labels to toriger renovate
    merge                            Update default.json from plugins/* definitions
    generate_matrix                  Generate matrix JSON from STDIN for GitHub Actions

Tests

$ make check
dprint check
./bin/cli lint
npx tsc
npm test
crystal spec
./bin/cli validate

File type

• Use *.json5 for all plugins to keep consistency. (Might be changed in future. VSCode does not run JSON schema for json5.)
• Do NOT use JSON5 extended features except comments, just using JSON5 as an alternative JSONC in this repo.

Define plugins

• github-releases will work in most cases. We have the scaffold. Run and update diff.
  • make scaffold PLUGIN=awesome-plugin-name
  • Add RE2 tests with actual data if it has extractVersionTemplate
• Some cases need struggling because of they have tricky versioning in github tags/releases. Examples are below.
  • Using renovate provided definitions
  • Using docker image for the datasource
  • Using multiple datasources because they have another repository in different versions
• When it is using no semantic versioning or customized one

Check actual Renovate behaviors

1. Intentionally specify old version into example definition.
2. Modify root config with executing make touch to trigger Renovate.
3. Check logs at dashboard.
   • Need private permissions.
   • Check in forked repo before sending to upstream helps me a lot.
4. Check PR has been sent as correct.

Basic Regex ensuring

Looks not in RE2, however https://regex101.com is useful. See https://regex101.com/r/L2micV as an actual example for gauche

Check actual RE2 behavior with Node.js

https://github.com/google/re2/wiki/Syntax is the reference.

Actual behavior checking requires https://github.com/uhop/node-re2 that include https://github.com/google/re2/.

$ npm install
$ npx tsx
Welcome to Node.js v20.4.0.
Type ".help" for more information.

> const RE2 = require("re2");
undefined
> let pattern = new RE2("^v(?<version>\\S+)");
undefined
> pattern.exec("v1.25.2");
[
  'v1.25.2',
  '1.25.2',
  index: 0,
  input: 'v1.25.2',
  groups: [Object: null prototype] { version: '1.25.2' }
]
> pattern.exec("v1.25.2").groups["version"];
'1.25.2'

Release new version with github-tags - # For maintainer

$ make release VERSION=0.4.2
Bumping to `0.4.2` ...
Done! you should manually push to GitHub with ...
$ git push origin 0.4.2
Completed!

Note

• Allowed syntax of default.json
• regexManagers
• datasource definitions
• versioning definitions