Skip to main content

Contributing

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

See also​

Changelog of development workflow​

We have been improving the development workflow continuously. So sometimes the development workflow is changed. Please check the change log.

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>
caution

cmdx s creates a commit, but please don't edit the commit by git commit --amend, git rebase, or somehow. cmdx s creates a commit to distinguish scaffolded code from manual changes. Please add new commits if you update code.

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.

  1. Fix generated files pkgs/<package name>/{pkg.yaml,registry.yaml} if necessary
  2. (Optional) Remove containers to clean up them if necessary: cmdx rm
  3. Run test: cmdx t <package name>
  4. Update registry.yaml: cmdx gr
info

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

  1. Commit registry.yaml and pkgs/<package name>/{pkg.yaml,registry.yaml
  2. Repeat the step 2 ~ 6 until packages are installed properly
  3. Create a pull request: cmdx new <package name>
  4. (Optional) Stop containers: cmdx stop

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.

💡 How to recreate containers​

We usually reuse same containers, but sometimes you would want to run test in new containers. In that case, you can remove containers by cmdx rm command. Then cmdx s and cmdx t create new containers.

💡 Set a GitHub Access token to avoid GitHub API rate limiting​

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>

How to execute a package in your machine during development​

There are several ways

  1. Execute a package in linux containers via cmdx con
  2. Import pkgs/<package>/pkg.yaml in aqua.yaml
  3. Add aqua-all.yaml in $AQUA_GLOBAL_CONFIG

1. Execute a package in linux containers via cmdx con​

$ cmdx con
+ bash scripts/connect.sh
[INFO] Connecting to the container aqua-registry (linux/arm64)

Then you can execute a package in the container.

2. Import pkgs/<package>/pkg.yaml in aqua.yaml​

packages:
  # ...
  - import: pkgs/<package>/pkg.yaml

Please don't commit this change.

You need to run aqua policy allow to use the local registry.

aqua policy allow

Then you can execute the package.

3. Add aqua-all.yaml in $AQUA_GLOBAL_CONFIG​

export AQUA_GLOBAL_CONFIG=$PWD/aqua-all.yaml:$AQUA_GLOBAL_CONFIG

You need to run aqua policy allow to use the local registry.

aqua policy allow

Then you can execute all packages.

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

Trouble shooting​

cmdx new fails to push a commit to the origin​

If cmdx new can't push a commit to a remote branch, please confirm if origin is not the upstream aquaproj/aqua-registry but your fork. If origin is not your fork, please change it to your fork.

e.g. Fail to push a commit

$ cmdx new pre-commit/pre-commit
# ...
+ git push origin feat/pre-commit/pre-commit
remote: Permission to aquaproj/aqua-registry.git denied to ***.
fatal: unable to access 'https://github.com/aquaproj/aqua-registry/': The requested URL returned error: 403
  1. If you haven't forked aquaproj/aqua-registry, please fork it.
  2. Check remote repositories.
git remote -v
  1. Please fix origin.
git remote set-url origin https://github.com/<your fork>
  1. Please set upstream if necessary.
git remote add upstream https://github.com/aquaproj/aqua-registry