Skip to main content

Contributing

How to contribute to Standard Registry. https://github.com/aquaproj/aqua-registry

See also​

Should you create an Issue before sending a Pull Request?​

Basically, you don't have to create an Issue before sending a Pull Request. But if the pull request requires the discussion before reviewing, you have to create an Issue in advance.

For example, you don't have to create an Issue in the following cases.

  • Add a package
  • Fix a typo

On the other hand, for example if you want to change the directory structure in pkgs or the workflow adding a package, you have to create an Issue and describe what is changed and why the change is needed.

aqua can't support some tools' plugin mechanism​

Some tools have the plugin mechanism.

e.g.

aqua simply installs commands in PATH (AQUA_ROOT_DIR/bin), but some of these plugins expect to be installed in the other location. If aqua can't support the plugin, we will reject the pull request adding the plugin to aqua-registry.

So if you send a pull request adding a plugin to aqua-registry, please check if aqua can support the plugin. We aren't necessarily familiar with the plugin, so please explain where the plugin expects to be installed and how the plugin works in the pull request description.

If you don't know well, please create a pull request and consult us.

Commit Signing​

All commits of pull requests must be signed. Please see the document.

Requirements​

Please use the latest version.

Set up​

git clone https://github.com/aquaproj/aqua-registry
cd aqua-registry
aqua i -l # Install dependencies

cmdx - Task Runner​

We use cmdx as a task runner. cmdx is installed by Set up already. We also use Docker to run tests in a container. Please run cmdx help and cmdx help <task> to show the help.

cmdx help
cmdx help scaffold

How to add a package​

  1. Scaffold configuration: cmdx s <package name>
  2. Fix generated files pkgs/<package name>/{pkg.yaml,registry.yaml
  3. Run test: cmdx t <package name>
  4. Repeat the step 2 and 3 until packages are installed properly
  5. Update registry.yaml: cmdx gr
  6. Create a pull request: cmdx new <package name>
  7. (Optional) Stop the container: cmdx stop
caution

Sometimes the scaffold by cmdx s <package name> would fail, but this is expected. In this case, please check the error message and fix pkgs/<package name>/{pkg.yaml,registry.yaml. Please check Troubleshooting too. If you can't figure out how to fix, please open a pull request and ask us for help.

info

If you face GitHub API rate limiting, please set the GitHub Access token with environment variable GITHUB_TOKEN or AQUA_GITHUB_TOKEN.

e.g.

export GITHUB_TOKEN=<YOUR PERSONAL ACCESS TOKEN>
info

When you update pkgs/**/registry.yaml, you have to run cmdx gr to reflect the update to registry.yaml on the repository root directory.

Use cmdx s definitely​

We don't accept pull requests not following this guide. Especially, we don't accept pull requests not using cmdx s. Standard Registry must support not only the latest version but also almost all versions and variaous platforms. Many tools have so many versions that people can't check all of them manually. So we can't trust the code not using cmdx s. cmdx s checks all GitHub Releases and generates code supporting all of them (Strictly speaking, if there are too many GitHub Releases we have to restrict the number of GitHub Releases, though cmdx s can still check over 200 versions). cmdx s generates much better code than us.

cmdx s isn't perfect and sometimes cmdx s causes errors and generates invalid code. Then you have to fix the code according to the error message. cmdx s supports only github_release type packages, so for other package types you have to fix the code. Even if so, you must still use cmdx s. cmdx s guarantees the quality of code.

Supported OS and CPU Architecture​

Please consider the following OS and CPU Architecture.

  • OS
    • windows
    • darwin
    • linux
  • CPU Architecture
    • amd64
    • arm64

We test the registry in CI on the above environments by GitHub Actions' build matrix.

Test multiple versions​

If the package has the field version_overrides, please add not only the latest version but also old versions in pkg.yaml to test if old versions can be installed properly.

e.g. pkg.yaml registry.yaml

packages:
  - name: scaleway/scaleway-cli@v2.12.0
  - name: scaleway/scaleway-cli
    version: v2.4.0

⚠️ Don't use the short syntax <package name>@<version> for the old version to prevent Renovate from updating the old version.

👎

packages:
  - name: scaleway/scaleway-cli@v2.12.0
  - name: scaleway/scaleway-cli@v2.12.0