From 6b3d6170a74fdea16b51c0cbd1ab052307e76f4b Mon Sep 17 00:00:00 2001 From: Shunsuke Suzuki Date: Thu, 26 Feb 2026 19:02:54 +0900 Subject: [PATCH 1/2] docs: add document for Coding Agent --- .claude/skills/fetch-doc/SKILL.md | 19 ++ .claude/skills/review/SKILL.md | 6 + .github/copilot-instructions.md | 3 + .gitignore | 1 + AGENTS.md | 24 +++ CONTRIBUTING.md | 14 +- docs/add_package.md | 180 +++++++++++++++++ docs/ai.md | 21 ++ docs/common_style.md | 20 ++ docs/error_handling.md | 164 ++++++++++++++++ docs/guide.md | 58 ++++++ docs/manner.md | 101 ++++++++++ docs/pkg_yaml.md | 52 +++++ docs/registry_yaml.md | 312 ++++++++++++++++++++++++++++++ docs/run_tool.md | 49 +++++ docs/structure.md | 17 ++ docs/support_policy.md | 45 +++++ docs/tool.md | 105 ++++++++++ docs/troubleshooting.md | 41 ++++ 19 files changed, 1231 insertions(+), 1 deletion(-) create mode 100644 .claude/skills/fetch-doc/SKILL.md create mode 100644 .claude/skills/review/SKILL.md create mode 100644 .github/copilot-instructions.md create mode 100644 docs/add_package.md create mode 100644 docs/ai.md create mode 100644 docs/common_style.md create mode 100644 docs/error_handling.md create mode 100644 docs/guide.md create mode 100644 docs/manner.md create mode 100644 docs/pkg_yaml.md create mode 100644 docs/registry_yaml.md create mode 100644 docs/run_tool.md create mode 100644 docs/structure.md create mode 100644 docs/support_policy.md create mode 100644 docs/tool.md create mode 100644 docs/troubleshooting.md diff --git a/.claude/skills/fetch-doc/SKILL.md b/.claude/skills/fetch-doc/SKILL.md new file mode 100644 index 00000000000..dadd0fa3b0a --- /dev/null +++ b/.claude/skills/fetch-doc/SKILL.md @@ -0,0 +1,19 @@ +--- +name: Fetch aqua Document +description: Fetch the document of aqua from the other repository aquaproj/aqua. This skill is useful when you want to know the specification of aqua. +--- + +The document of aqua is hosted at https://github.com/aquaproj/aqua. +So please checkout the repository and refer the document. + +```sh +mkdir -p .ai +if [ ! -d .ai/aqua ]; Then + git clone https://github.com/aquaproj/aqua .ai/aqua +fi +cd .ai/aqua +git pull origin main +``` + +Then please see .ai/aqua/website/docs. +Especially, about the registry settings, please see .ai/aqua/website/docs/reference/registry-config/*.md. diff --git a/.claude/skills/review/SKILL.md b/.claude/skills/review/SKILL.md new file mode 100644 index 00000000000..9d27506bb64 --- /dev/null +++ b/.claude/skills/review/SKILL.md @@ -0,0 +1,6 @@ +--- +name: review-change +description: Review changes. Use this skill when adding or changing pkgs/**/*.yaml +--- + +Please review pkgs/**/*.yaml according to CONTRIBUTING.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000000..8724264fdda --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,3 @@ +## Review + +Please review changes according to .claude/skills/review-change/SKILL.md. diff --git a/.gitignore b/.gitignore index 61cc78c17cf..a6c2dd77a5c 100644 --- a/.gitignore +++ b/.gitignore @@ -5,3 +5,4 @@ aqua-checksums.json .build docker/aqua-policy.yaml aqua-generate-registry.yaml +.ai diff --git a/AGENTS.md b/AGENTS.md index 6c1ed4a76d2..2ad75bc5757 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1 +1,25 @@ @CONTRIBUTING.md + +## Checkout the document from aqua repository + +The document of aqua is hosted at https://github.com/aquaproj/aqua. +So please checkout the repository and refer the document. + +```sh +mkdir -p .ai +if [ ! -d .ai/aqua ]; Then + git clone https://github.com/aquaproj/aqua .ai/aqua +fi +cd .ai/aqua +git pull origin main +``` + +Then please see .ai/aqua/website/docs. +Especially, about the registry settings, please see .ai/aqua/website/docs/reference/registry-config/*.md. + +JSON Schema: + +- registry.yaml: .ai/aqua/json-schema/registry.json + +The link to the document https://aquaproj.github.io/docs/... can be found at .ai/aqua/website/docs/... +If the document includes a link to https://aquaproj.github.io/docs/, please look at .ai/aqua/website/docs/... diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d9cd8518afb..4e34c8fab8b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,3 +1,15 @@ # Contributing -Please see [Contributing](https://aquaproj.github.io/docs/products/aqua-registry/contributing). +- [Manner](docs/manner.md) +- [AI Guide](docs/ai.md) +- [Support Policy](docs/support_policy.md) +- [Repository Structure](docs/structure.md) +- [Development Tools](docs/tool.md) +- [Common Style Guide](docs/common_style.md) +- [Registry Style Guide](docs/registry_yaml.md) +- [pkg.yaml Guide](docs/pkg_yaml.md) +- [Development Guide](docs/guide.md) +- [Adding New Tools](docs/add_package.md) +- [Tool Installation Error Handling](docs/error_handling.md) +- [How to execute a package in your machine during development](docs/run_tool.md) +- [Troubleshooting](docs/troubleshooting.md) diff --git a/docs/add_package.md b/docs/add_package.md new file mode 100644 index 00000000000..ad6204e9000 --- /dev/null +++ b/docs/add_package.md @@ -0,0 +1,180 @@ +# Adding New Tools + +When submitting a Pull Request to add a new tool, there's no need to create an Issue. + +Run `cmdx s` to auto-generate code. + +```sh +cmdx s "" +``` + +e.g. + +```sh +cmdx s cli/cli +``` + +For package types other than github_release, specify `-l 1`. + +```sh +cmdx s -l 1 "" +``` + +cmdx s generates a branch `feat/`, code, and commit, and tests using containers. + +:::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. +::: + +:::info +This command may sometimes fail tests and output a large amount of error messages, but don't be overwhelmed by those error messages. +Test failures are expected. +::: + +## Customizing cmdx s with Configuration File + +:::note +In many cases, this is unnecessary. +Also, you should not use this feature carelessly. +::: + +Sometimes `cmdx s` generation doesn't work in one go. +For github_release packages, `cmdx s` gets lists of GitHub Releases and assets via GitHub API and auto-generates configuration based on that. +However, sometimes you need to exclude specific versions or assets. +For example, if multiple CLIs are published in the same repository, if you don't exclude assets from other CLIs, code might be generated based on asset names from other CLIs. +Also, if multiple tools are published in the same repository, versions might have different prefixes for different tools. +In that case, if you don't ignore versions from other tools, code likely won't be generated correctly. + +In such cases, follow these steps: + +1. Generate a template configuration file `aqua-generate-registry.yaml` for `cmdx s` with `aqua gr -init ` +2. Modify the configuration file `aqua-generate-registry.yaml` +3. Generate code with `cmdx s -c "" ""` + +You can configure the following: + +- `version_filter`: Versions not matching this condition are excluded +- `version_prefix`: Versions without this prefix are excluded +- `all_assets_filter`: Assets not matching this condition are excluded + +However, using this feature carelessly can exclude things that shouldn't be excluded, so it shouldn't be used lightly. +`all_assets_filter` in particular requires caution. This is because it can accidentally exclude checksum files like `SHA256SUM` or `checksums.txt`, and it's difficult to notice if you've excluded them. +Therefore, you should first generate code without exclusion settings, and if unnecessary things are mixed in the generated code, write settings that explicitly exclude only those (without making the scope too broad to avoid excluding extra things). + +:::caution +Note that `version_filter` is not a feature for dropping support for old versions. +`version_constraint`, `no_asset`, and `error_message` are used for dropping support for old versions. + +https://github.com/aquaproj/aqua-registry/blob/191f2136c10b1eb962dd43c8f421af417b1b3a16/pkgs/Shopify/ejson/registry.yaml#L8-L10 +::: + +## Retrying `cmdx s` Until It Works + +:::note +In many cases, this is unnecessary. +::: + +As mentioned earlier, code generation with `cmdx s` doesn't always work on the first try. +Sometimes you need to repeat it several times. + +1. Generate code without configuration file `cmdx s` +2. Check the generated code, and if extra versions or assets are included, delete the generated branch + +`cmdx s` generates a branch and commit, but if it's before opening a Pull Request, you can delete them without problems. + +```sh +git checkout main +git branch -D "feat/" +``` + +3. Generate configuration file `aqua gr -init` +4. Modify configuration file and generate code `cmdx s` +5. Repeat 2, 4 until extra versions and assets are excluded + +## Modifying Manually + +If installation of multiple versions is failing and the log is hard to read, it's good to comment out some versions in pkg.yaml and tackle problems one by one. +When modifying configuration, refer to [Manual Modification](#manual-modification) and [Style Guide](/docs/develop-registry/registry-style-guide/). +After modification, run `cmdx t` to confirm it can be installed correctly. +Repeat modification and confirmation until it can be installed. + +When you're done with modifications, or if you're not sure how to fix it, submit a Pull Request. + +:::note +The `cmdx new` command has been removed from the standard procedure. +However, the command itself remains and can still be used. +This command has large environment dependencies and didn't work well for some users, making troubleshooting and support difficult. +Since you can create Pull Requests without using `cmdx new`, we decided to remove it from the standard procedure. +[See also changelog.](/docs/products/aqua-registry/changelog#why-did-we-remove-cmdx-new-from-the-guide) +::: + +## 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 [various platforms](#supported-os-and-cpu-architecture). +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. + +## :bulb: How to ignore some assets and versions + +You can ignore some assets and versions to scaffold better configuration files. + +:::caution +Be careful to use this feature as it may exclude assets and versions unexpectedly. +Especially, `all_assets_filter` may exclude assets such as checksum files. +We recommend to scaffold codes without this feature first. +Then if `cmdx s` can't scaffold good codes due to some noisy versions or assets, you should re-scaffold code using this feature. +About `all_assets_filter`, we recommend specifying patterns to exclude assets (deny list) rather than specifying patterns to include assets (allow list). + +e.g. + +```yaml +all_assets_filter: not (Asset contains "static") +``` +::: + +1. Create `aqua-generate-registry.yaml` by `aqua gr --init` command: + +```sh +aqua gr --init +``` + +2. Edit `aqua-generate-registry.yaml`: + +Example 1. Filter assets: + +```yaml +name: argoproj/argo-rollouts +all_assets_filter: not ((Asset matches "rollouts-controller") or (Asset matches "rollout-controller")) +``` + +Example 2. Filter versions by `version_prefix`: + +```yaml +name: grpc/grpc-go/protoc-gen-go-grpc +version_prefix: cmd/protoc-gen-go-grpc/ +``` + +Example 3. Filter versions by `version_filter`: + +```yaml +name: crate-ci/typos +version_filter: not (Version startsWith "varcon-") +``` + +3. Run `cmdx s` with `aqua-generate-registry.yaml` + +```sh +cmdx s -c aqua-generate-registry.yaml +``` diff --git a/docs/ai.md b/docs/ai.md new file mode 100644 index 00000000000..d664f530aed --- /dev/null +++ b/docs/ai.md @@ -0,0 +1,21 @@ +# AI Guide + +## Ask AI for Help + +For simple questions or bugs, try asking AI tools such as DeepWiki or Claude Code. +You may be able to resolve issues much faster without waiting for a maintainer’s response. +Sharing AI-generated investigation results or proposed fixes in an issue can also help maintainers. +Rather than leaving everything to maintainers, actively using AI to investigate problems and showing a cooperative attitude can make it easier to receive support from them. +This project doesn't restrict the use of AI. + +## Have AI Review Issues and Pull Requests + +Have AI review your issues and pull requests to check whether all necessary information is included and to improve their overall quality. The questions AI asks you to clarify are often the same things maintainers would want to confirm. + +## Take Responsibility for AI-Generated Content + +When using AI to create issues or pull requests, clearly disclose that AI was used. +For example, you can add an AI agent as a co-author in commits or explicitly note when quoting AI-generated responses. + +Before sharing AI-generated content, review it carefully and take responsibility for it. +If maintainers ask questions about the content, responding with “I don’t know because it was generated by AI” is not acceptable. diff --git a/docs/common_style.md b/docs/common_style.md new file mode 100644 index 00000000000..0eab337f4ce --- /dev/null +++ b/docs/common_style.md @@ -0,0 +1,20 @@ +# Common Style + +## Add a newline at the end of file + +Please add a newline at the end of file. +Note that this doesn't mean add an empty line at the end of file. + +image + +The mark ⛔ means the file misses a newline at the end of file. + +image + +> No newline at end of file + +If you use VSCode, we recommend setting `"files.insertFinalNewline": true`. + +https://stackoverflow.com/questions/44704968/visual-studio-code-insert-newline-at-the-end-of-files + +Reference: [Why should text files end with a newline?](https://stackoverflow.com/a/729795/6364492) diff --git a/docs/error_handling.md b/docs/error_handling.md new file mode 100644 index 00000000000..5bc872b39fe --- /dev/null +++ b/docs/error_handling.md @@ -0,0 +1,164 @@ +# Tool Installation Error Handling + +## When Configuration Needs to Change for Specific Versions + +You can change configuration by version using [version_overrides and version_constraint](https://aquaproj.github.io/docs/reference/registry-config/version-overrides). + +## When Configuration Needs to Change for Specific OS/Arch + +You can change configuration by OS/Arch with [overrides](https://aquaproj.github.io/docs/reference/registry-config/overrides). + +## When Version Cannot Be Found + +Sometimes a released version is deleted and disappears. +In that case, delete that version from pkg.yaml. +And delete configuration related to that version from registry.yaml (if any). +However, [no_asset](https://aquaproj.github.io/docs/reference/registry-config/no_asset) and [error_message](https://aquaproj.github.io/docs/reference/registry-config/error_message) don't need to be deleted. +You may or may not add `no_asset` and `error_message`. + +## When Asset Cannot Be Found + +When an asset cannot be found, either the asset name is wrong or the asset hasn't been released. + +Running the `cmdx lsa [-r ] ""` command outputs a list of assets, which is convenient. + +```console +$ cmdx lsa -repo suzuki-shunsuke/pinact v3.0.0 ++ REPO=${REPO#https://github.com/} +repo=$(bash scripts/get_test_pkg.sh "$REPO") + +gh release view --json assets --jq ".assets[].name" -R "$repo" "$VERSION" + +multiple.intoto.jsonl +pinact_3.0.0_checksums.txt +pinact_3.0.0_checksums.txt.pem +pinact_3.0.0_checksums.txt.sig +pinact_darwin_amd64.tar.gz +pinact_darwin_arm64.tar.gz +pinact_linux_amd64.tar.gz +pinact_linux_arm64.tar.gz +pinact_windows_amd64.zip +pinact_windows_arm64.zip +``` + +It's common for new GitHub Releases or tags to be released without assets being released. +When there are no assets, the following causes are possible: + +1. Release is simply delayed. It will be released if you wait +2. CI failed midway and wasn't released +3. CI skipped the release + +These are not problems with aqua or aqua-registry. +For example, if such a problem occurs with [suzuki-shunsuke/pinact](https://github.com/suzuki-shunsuke/pinact) and you want to take action, it would be good to create an issue or PR at https://github.com/suzuki-shunsuke/pinact. +As aqua-registry maintainers, we often encounter these problems. +Each time, we report problems to various repositories or fix CI. + +It's common for specific os/arch not to be supported. +In that case, you need to exclude that os/arch from `supported_envs`. + +If the asset name is wrong, the asset naming convention may have changed from a certain version. +For example, the GoReleaser configuration was modified and the format became zip, or the version disappeared from the asset name, etc. +In that case, you need to modify the asset in registry.yaml. +If the name changed due to a mistake on the tool side, it would be kind to report the problem or create a PR to fix it. + +## When Command Cannot Be Found + +When a command cannot be found, the following possibilities exist: + +1. Command name is wrong +2. Command name changed +3. Path is wrong +4. Target os/arch is excluded by supported_envs + +In these cases, you need to modify the `files` configuration. + +```yaml +files: + - name: + src: +``` + +By default, the command name is the last element when splitting the package name by `/`. +So for `cli/cli` it becomes `cli`, but the actual command name is `gh`, so you need to explicitly specify `files`. + +```yaml +files: + - name: gh +``` + +Note that even on Windows, `.exe` is not added to the name. + +`src` is the relative path where the command executable is located when extracting assets like tarball or zip. +By default, it's the same as `name`. +For gh, since the path is different, you need to specify `src`. + +```yaml + files: + - name: gh + src: gh_{{trimV .Version}}_{{.OS}}_{{.Arch}}/bin/gh +``` + +https://github.com/aquaproj/aqua-registry/blob/dc98ca0c3314ae3cface74556a295a4cb0a95918/pkgs/cli/cli/registry.yaml#L7-L9 + +The auto-generation tool currently cannot auto-generate `files`. +Therefore, manual modification is necessary. + +## Adding Support for Specific OS / Architecture + +Sometimes a tool supports new OS/Architecture from a specific version but it's not reflected in registry.yaml and remains uninstallable. +In that case, you need to add that OS/Architecture to `supported_envs`. + +## When Checksum Cannot Be Extracted from Checksum File + +Please see [the document](https://aquaproj.github.io/docs/reference/registry-config/checksum). + +## When Checksum Verification Fails + +Please see [the document](https://aquaproj.github.io/docs/reference/registry-config/checksum). + +1. Checksum written in checksum file is wrong => Disable checksum + +```yaml +checksum: + enabled: false +``` + +Or delete the checksum configuration since it's disabled by default. + +:::info +The checksum enable/disable setting in registry configuration is just a setting for "whether to download checksum file and get checksum". +Even if this is disabled, if checksum verification is enabled in aqua.yaml, checksum verification will be performed. +In that case, it actually downloads the asset, calculates the checksum, and records it in aqua-checksums.json. +There is also an issue for getting checksum via GitHub API. +::: + +2. Extracting wrong string from checksum file + +Modify extraction parameters or disable checksum. + +3. Wrong checksum algorithm (sha1, sha256, sha512, md5, etc) => Fix the algorithm + +## When cosign Verification Fails + +[Please see the document](https://aquaproj.github.io/docs/reference/registry-config/cosign). + +## When SLSA Provenance Verification Fails + +[Please see the document](https://aquaproj.github.io/docs/reference/registry-config/slsa-provenance). + +## When GitHub Artifact Attestations Verification Fails + +[Please see the document](https://aquaproj.github.io/docs/reference/registry-config/github-artifact-attestations). + +`signer_workflow` might be wrong. +If attestations are not generated for a specific version in the first place, delete the github_artifact_attestations configuration. + +The github_artifact_attestations configuration cannot be auto-generated currently. +Therefore, when adding a new tool, check if attestations are generated and add the configuration if they are. + +## When Minisign Verification Fails + +[Please see the document](https://aquaproj.github.io/docs/reference/registry-config/minisign). + +The minisign configuration might be wrong. +If minisign signing is not performed for a specific version in the first place, delete the minisign configuration. diff --git a/docs/guide.md b/docs/guide.md new file mode 100644 index 00000000000..114468f53f3 --- /dev/null +++ b/docs/guide.md @@ -0,0 +1,58 @@ +# Guide + +## Do Not Change the Source of Existing Packages to a Fork + +Even if maintenance of an existing package’s source has stalled or the repository has been archived, **do not change the package source to point to a fork**. +Instead, create a **new package** that points to the forked source. + +For example, development of [99designs/aws-vault](https://github.com/99designs/aws-vault) has slowed down, and a fork, [ByteNess/aws-vault](https://github.com/ByteNess/aws-vault), was created. +[Homebrew switched to using the forked repository](https://github.com/Homebrew/homebrew-core/pull/226185), but in the aqua registry, we decided to keep the original package as-is and add a new package instead. + +- https://github.com/99designs/aws-vault/issues/1269 +- https://github.com/aquaproj/aqua-registry/pull/45430 + +This is to prevent the maintainer of a package’s source from changing without users’ knowledge. +Whether or not to switch to a fork should be a decision made by users, not by the maintainers of the aqua registry. +By adding a new package, users can explicitly choose to switch packages themselves. + +## Modifying Existing Packages + +When modifying existing packages, you need to modify code under `pkgs/`. +There are several modification methods: + +1. Manually modify the code +2. Regenerate the code from scratch with commands +3. Auto-generate code for the latest version and manually modify based on that + +Which method to use depends on the state of the original code. +Code auto-generation has been improved many times. +Therefore, there is low-quality code generated before improvements. +Such code may be better regenerated from scratch rather than manually fixed. + +One characteristic to identify if code is old is how `version_constraint` and `version_overrides` are written. +In the new style, it basically looks like this: + +```yaml + version_constraint: "false" # Root version_constraint is "false" + version_overrides: + - version_constraint: semver("<= 0.1.0") # Version constraints use <, <= not >, >= (basically <=) + # ... + # ... + - version_constraint: "true" # End with "true" for latest version configuration + # ... +``` + +In the old style, `version_overrides` is often not defined. +In this case, it's likely better to regenerate from scratch. +However, as mentioned earlier, auto-generation doesn't support package types other than `github_release` or `cargo`, so manual modification will be necessary. + +Also, [aliases](https://aquaproj.github.io/docs/reference/registry-config/aliases) and [files](https://aquaproj.github.io/docs/reference/registry-config/files) cannot be auto-generated, so you need to modify the auto-generated code referring to the original code. + +`3. Auto-generate code for the latest version and manually modify based on that` is effective when the package no longer installs with the latest version but you want to reuse existing code (don't want to regenerate from scratch). +Running the following command generates code for the latest version: + +```sh +aqua gr -l 1 "" +``` + +Fix this and add it to the end of `version_overrides` in the original code and modify version_constraint. diff --git a/docs/manner.md b/docs/manner.md new file mode 100644 index 00000000000..a7bdd871ee2 --- /dev/null +++ b/docs/manner.md @@ -0,0 +1,101 @@ +# Manner + +## Use English + +Please use English in this project. +If you're not good at English, machine translator such as [DeepL](https://www.deepl.com/translator) would help you. + +## Should you create an Issue before sending a Pull Request? + +In many cases, 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. + +## Describe the detail as much as possible. Don't neglect to explain + +The lack of information would make unneeded conversation and misunderstanding. +It would help if you were careful maintainers can handle the Issue comfortably. + +## Use GitHub Flavored Markdown properly + +Especially, you should use [fenced code blocks](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks). +Fenced code blocks make a comment easy to read. +The readability of code without fenced block is terrible. + +## Write good `How to reproduce` + +Please write the following information. + +- Environment + - OS (e.g. Windows, macOS, Ubuntu) + - Arch (e.g. amd64, arm64) + - tool versions: If multiple tools are used, you should write all tool versions +- Code +- command and result +- `Expected Behavior` and `Actual Behavior` +- Debug Log + +If you try multiple versions, you should describe the result too. +`Code` and `command` should be minimum, reproducible, and executable. + +Code unrelated to the issue should be removed. +Everyone should be able to execute the code and reproduce the problem according to `How to reproduce`. +Code shouldn't be partial because partial code isn't executable. + +Private resources shouldn't be used in `How to reproduce` if it isn't needed. +For example, if you can reproduce the issue with public Docker images, you shouldn't use private Docker images. + +`Expected Behavior` and `Actual Behavior` should be clear. +For example, a report such as `an error occurs` and `the tool doesn't work` is ambiguous. +If an error occurs, you should paste the command and standard (error) output. +A screenshot may also be helpful, but a text in the screenshot can't be copied so you should paste the output as text too. + +## Don't do force pushes after opening pull requests + +After opening pull requests, please don't do force pushes because force pushes make it difficult for maintainers to review the diff. +And if maintainers push commits to pull requests, your force push may eliminate maintainers' commits. +Instead of force pushes, you should push new commits, then maintainers can review the diff. + +For example, when maintaiers request a change to you, if you push a new commit maintainers can review it easily, but if you do a force push, maintainers can't understand easily what is changed by force push so the review is difficult. + +As an exception, if maintainers ask you to make commits history clean by rebasing, you should follow the request. + +## Separate commits that code was created or updated by command + +Please separate commits generated by command with manual changes. +And please show the command in the commit message. +This makes changes easy to understand and review. + +## Sign commits + +Please configure your Git client to sign commits. +In this project, pull requests with not signed commits can't be merged. +If you have already opened a pull request with not signed commits, there are several options: + +1. Rebase commits to sign them and do force push. [As we describe above](#dont-do-force-pushes-after-opening-pull-requests), force push isn't desirable, but it can't be helped +2. Open a new pull request with signed commits + +About commit signing, please see the following document: + +- [Signing commits - GitHub](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits) +- [Generating a new GPG key - GitHub](https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key) +- [Adding a GPG key to your GitHub account - GitHub](https://docs.github.com/en/authentication/managing-commit-signature-verification/adding-a-gpg-key-to-your-github-account) + +## Allow changes to a pull request branch created from a fork + +[Allowing changes to a pull request branch created from a fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork) + +Please allow maintainers to push commits to your pull requests so that maintainers can collaborate with you well. + +### Don't fork repositories into GitHub Organizations for sending pull requests + +You can't allow maintainers to push commits to your pull requests if fork repositories belong to not GitHub User but GitHub Organization. +This is the limitation of GitHub. +So please fork repositories into your GitHub User Account instead of GitHub Organization. diff --git a/docs/pkg_yaml.md b/docs/pkg_yaml.md new file mode 100644 index 00000000000..4ac429a8145 --- /dev/null +++ b/docs/pkg_yaml.md @@ -0,0 +1,52 @@ +# Style Style Guide of pkgs/**/pkg.yaml + +## What's pkgs/**/pkg.yaml for? + +`pkgs/**/pkg.yaml` are test data. +`pkgs/**/pkg.yaml` are used to test if packages can be installed properly. + +Note that `pkgs/**/pkg.yaml` aren't lists of available versions. +You can install any versions not listed in `pkgs/**/pkg.yaml`. + +## packages must not be empty + +:thumbsdown: + +```yaml +packages: [] +``` + +If `cmdx s` fails to fetch versions, packages may become empty. + +## Test multiple versions + +If the package has the field [version_overrides](/docs/reference/registry-config/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. + +```yaml +packages: + - name: scaleway/scaleway-cli@v2.12.0 + - name: scaleway/scaleway-cli + version: v2.4.0 +``` + +## Don't use the short syntax `@` for the old versions + +Don't use the short syntax `@` for the old version to prevent aqua-registry-updater from updating the old version. + +:thumbsup: + +```yaml +packages: + - name: scaleway/scaleway-cli@v2.12.0 + - name: scaleway/scaleway-cli + version: v2.4.0 +``` + +:thumbsdown: + +```yaml +packages: + - name: scaleway/scaleway-cli@v2.12.0 + - name: scaleway/scaleway-cli@v2.4.0 +``` diff --git a/docs/registry_yaml.md b/docs/registry_yaml.md new file mode 100644 index 00000000000..54d7662b9f4 --- /dev/null +++ b/docs/registry_yaml.md @@ -0,0 +1,312 @@ +# Style Guide of pkgs/**/registry.yaml + +## Tool Naming Convention + +To avoid name conflicts, tool names must include `/` (namespace-like meaning). + +- NG: `terraform` +- OK: `hashicorp/terraform` + +If the tool code is managed on GitHub, match the repository name. +If multiple tools are managed in that repository, change the name for each tool. + +e.g. [winebarrel/cronplan](https://github.com/winebarrel/cronplan) + +- `winebarrel/cronplan/cronmatch` +- `winebarrel/cronplan/cronplan` +- `winebarrel/cronplan/cronviz` + +Packages hosted outside GitHub should have naming that distinguishes them from GitHub. +`cargo` packages become [crates.io/{crate name}](https://github.com/aquaproj/aqua-registry/tree/main/pkgs/crates.io). +Platforms other than GitHub like GitLab are not actively supported, but some are supported as http type packages. +[GitLab uses `gitlab.com/`.](https://github.com/aquaproj/aqua-registry/tree/main/pkgs/gitlab.com) + +## YAML Language Server Comment is necessary at the top of pkgs/**/registry.yaml + +```yaml +# yaml-language-server: $schema=https://raw.githubusercontent.com/aquaproj/aqua/main/json-schema/registry.json +``` + +## Remove spaces in the template `{{ ` and ` }}` + +:thumbsup: + +```yaml +asset: tfcmt_{{.OS}}_{{.Arch}}.tar.gz +``` + +:thumbsdown: + +```yaml +asset: tfcmt_{{ .OS }}_{{ .Arch }}.tar.gz +``` + +## Remove characters `.!` from the end of the description + +:thumbsup: + +```yaml +description: A command-line tool that makes git easier to use with GitHub +``` + +:thumbsdown: + +```yaml +description: A command-line tool that makes git easier to use with GitHub. +``` + +## Trim spaces + +:thumbsup: + +```yaml +description: A command-line tool that makes git easier to use with GitHub +``` + +:thumbsdown: + +```yaml +description: " A command-line tool that makes git easier to use with GitHub " +``` + +## Remove unneeded quotes of strings + +:thumbsup: + +```yaml +description: A command-line tool that makes git easier to use with GitHub +``` + +:thumbsdown: + +```yaml +description: "A command-line tool that makes git easier to use with GitHub" +``` + +## Avoid `if` and `for` statement in templates + +:thumbsup: + +```yaml +asset: foo.{{.Format}} +format: tar.gz +overrides: + - goos: windows + format: zip +``` + +:thumbsdown: + +```yaml +asset: 'foo.{{if eq .GOOS "windows"}}zip{{else}}tar.gz{{end}}' +``` + +## `version_overrides` Style Guide + +We decided not to rely on base settings as much as possible. +This means we don't define settings such as `asset`, `format`, `windows_arm_emulation`, and so on on the base settings. +Merge with base settings makes code DRY, but it's difficult to update settings when settings of new versions are changed because the update of the base settings affects all version override. +By stopping to merge settings, we can update settings by simply adding a new version override and updating the last version_constraint. +Perhaps we would be able to automate the update in future too. + +e.g. + +```yaml +# Define only settings which don't depend on versions. +# e.g. repo_owner, repo_name, description. +version_constraint: "false" +version_overrides: + - version_constraint: semver("<= 3.0.0") + # Oldest setting + # ... + - version_constraint: semver("<= 4.0.0") + # ... + - version_constraint: semver("<= 5.0.0") + # ... + - version_constraint: "true" + # Latest setting + # ... +``` + +## If the `format` is `raw`, `files[].src` isn't needed + +:thumbsup: + +```yaml +format: raw +files: + - name: swagger +``` + +:thumbsdown: + +```yaml +format: raw +files: + - name: swagger + src: swagger_{{.OS}}_{{.Arch}} # unneeded +``` + +## Consideration about Rust + +:warning: The author [@suzuki-shunsuke](https://github.com/suzuki-shunsuke) isn't familiar with Rust. If you have any opinion, please let us know. + +- linux: use the asset for not `gnu` but `musl` if both of them are supported + - ref: https://github.com/aquaproj/aqua-registry/pull/2153#discussion_r805116879 +- windows: use the asset for not `gnu` but `msvc` if both of them are supported + - ref: https://rust-lang.github.io/rustup/installation/windows.html + +:thumbsup: + +```yaml +replacements: + linux: unknown-linux-musl + windows: pc-windows-msvc +``` + +:thumbsdown: + +```yaml +replacements: + linux: unknown-linux-gnu + windows: pc-windows-gnu +``` + +## Use `overrides` instead of `format_overrides` + +:thumbsup: + +```yaml +format: tar.gz +overrides: + - goos: windows + format: zip +``` + +:thumbsdown: + +```yaml +format: tar.gz +format_overrides: + - goos: windows + format: zip +``` + +## Don't use emojis as much as possible + +In some environments, emojis are corrupted. e.g. https://github.com/aquaproj/aqua/pull/1004#issuecomment-1183710603 + +:thumbsup: + +```yaml +description: CLI and Go library for CODEOWNERS files +``` + +:thumbsdown: + +```yaml +description: 🔒 CLI and Go library for CODEOWNERS files +``` + +## Omit the setting which is equivalent to the default value + +When `repo_owner` and `repo_name` are set, you can omit some attributes. + +:thumbsup: + +```yaml +repo_owner: weaveworks +repo_name: eksctl +``` + +:thumbsdown: + +```yaml +repo_owner: weaveworks +repo_name: eksctl +name: weaveworks/eksctl +link: https://github.com/weaveworks/eksctl +files: + - name: eksctl +``` + +## Omit `.files[].src` if it is the same as `.files[].name` + +:thumbsup: + +```yaml +files: + - name: pinact +``` + +:thumbsdown: + +```yaml +files: + - name: pinact + src: pinact +``` + +## Don't add `.exe` to `.files[].name` + +:thumbsup: + +```yaml +files: + - name: pinact +``` + +:thumbsdown: + +```yaml +files: + - name: pinact.exe +``` + +## Omit `.exe` + +On Windows, `.exe` is appended by default. So you don't need to append `.exe`. + +:thumbsup: + +```yaml +files: + - name: pinact +``` + +:thumbsdown: + +```yaml +files: + - name: pinact + src: pinact.exe +``` + +## Use `aliases` only for keeping the compatibility + +The same package should have only one name, and aliases should be used only to keep the compatibility. +`aliases` is used when the package repository is transferred usually. +`search_words` is useful to allow to search packages with additional words. + +e.g. + +```yaml +name: kubernetes-sigs/controller-tools/controller-gen +search_words: + - kubebuilder +``` + +## Select `type` according to the following order + +1. github_release +1. github_content +1. github_archive +1. http +1. go_install +1. go_build + +For example, you can also use `http` type to install the package from GitHub Releases, but in that case you should use `github_release` rather than `http`. + +## `cargo` package name should be `crates.io/` + +Please see [here](/docs/reference/registry-config/cargo-package#-package-name). diff --git a/docs/run_tool.md b/docs/run_tool.md new file mode 100644 index 00000000000..3e8858806bf --- /dev/null +++ b/docs/run_tool.md @@ -0,0 +1,49 @@ +# How to execute a package in your machine during development + +There are several ways + +1. Execute a package in linux containers via `cmdx con` +1. Import `pkgs//pkg.yaml` in [aqua.yaml](https://github.com/aquaproj/aqua-registry/blob/main/aqua.yaml) +1. Add [aqua-all.yaml](https://github.com/aquaproj/aqua-registry/blob/main/aqua-all.yaml) in `$AQUA_GLOBAL_CONFIG` + +## 1. Execute a package in linux containers via `cmdx con` + +```console +$ 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//pkg.yaml` in aqua.yaml + +```yaml +packages: + # ... + - import: pkgs//pkg.yaml +``` + +Please don't commit this change. + +You need to run `aqua policy allow` to use the local registry. + +```sh +aqua policy allow +``` + +Then you can execute the package. + +## 3. Add aqua-all.yaml in `$AQUA_GLOBAL_CONFIG` + +```sh +export AQUA_GLOBAL_CONFIG=$PWD/aqua-all.yaml:$AQUA_GLOBAL_CONFIG +``` + +You need to run `aqua policy allow` to use the local registry. + +```sh +aqua policy allow +``` + +Then you can execute all packages. diff --git a/docs/structure.md b/docs/structure.md new file mode 100644 index 00000000000..af53927e45f --- /dev/null +++ b/docs/structure.md @@ -0,0 +1,17 @@ +# Repository Structure + +Package-related code is located in the `pkgs/` directory of https://github.com/aquaproj/aqua-registry. +e.g. [cli/cli](https://github.com/aquaproj/aqua-registry/tree/main/pkgs/cli/cli) +Each package directory contains the following files: + +- pkg.yaml: List of versions installed during testing. This is essentially test data +- registry.yaml: Configuration. Each tool's registry.yaml is merged to generate the repository root registry.yaml +- scaffold.yaml: Optional. Configuration file for commands that auto-generate pkg.yaml and registry.yaml. Required when you want to change the auto-generation behavior + +:::note +pkg.yaml is just test data. You can install versions not included in this file. +::: + +There is also a registry.yaml at the repository root, which is a huge YAML file merging all registry.yaml files under `pkgs`. +When specifying Standard Registry in aqua.yaml, this repository root registry.yaml is referenced. +To modify the repository root registry.yaml, modify the registry.yaml under pkgs and run the `cmdx gr` command. diff --git a/docs/support_policy.md b/docs/support_policy.md new file mode 100644 index 00000000000..47c20b60b40 --- /dev/null +++ b/docs/support_policy.md @@ -0,0 +1,45 @@ +# Support Policy + +## aqua can't support some tools' plugin mechanism + +Some tools have the plugin mechanism. + +e.g. + +- [GitHub CLI Extension](https://docs.github.com/en/github-cli/github-cli/creating-github-cli-extensions) +- [Terraform provider](https://developer.hashicorp.com/terraform/language/providers) +- [Gauge plugin](https://docs.gauge.org/plugin.html?os=macos&language=java&ide=null) +- etc + +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. + +## Note of Programming Language Support + +aqua supports several programming languages such as Go and Node.js, but when we support a programming language, we need to be careful about where the programming language installs libraries and commands. + +For instance, if the programming language installs commands in the same directory with the programming language itself, aqua can't add them to $PATH, meaning we can't execute them. +aqua doesn't support changing $PATH dynamically (We have no plan to support it as it makes aqua more complicated). +Node.js's `npm i -g` installs the same directory with node by default, so we gave up the support of Node.js before (Now aqua supports Node.js again because we can change the install path by `NPM_CONFIG_PREFIX`). +If the language installs libraries in the same directory with it, the language can't refer installed libraries when we change the version of the language. + +So before supporting a programming language, we should consider carefully if it really works well. +Many programming languages have dedicated version managers, so maybe they are more appropriate. + +## Supported OS and CPU Architecture + +Please consider the following OS and CPU Architecture. +We test the registry in CI on the above environments by GitHub Actions' build matrix. + +- OS + - windows + - darwin + - linux +- CPU Architecture + - amd64 + - arm64 diff --git a/docs/tool.md b/docs/tool.md new file mode 100644 index 00000000000..41c958368e0 --- /dev/null +++ b/docs/tool.md @@ -0,0 +1,105 @@ +# Development Tools + +Unfortunately, the current development tools depend on Shell Scripts and are unlikely to work on Windows (though they probably work on WSL). +[There is an issue to rewrite them in Go.](https://github.com/aquaproj/aqua-registry/issues/32699) + +CLIs for developing aqua-registry are provided. +These can be installed with aqua. +Check out aqua-registry and run `aqua i -l`. + +```sh +aqua i -l +``` + +We use a task runner called [cmdx](https://github.com/suzuki-shunsuke/cmdx). +You can check tasks with `cmdx help`. + +```sh +cmdx help +``` + +Using development tools, you can generate files for each package (pkg.yaml, registry.yaml, scaffold.yaml) and test tool installation in containers. +Tests are performed in containers using the docker command, so you need the docker command and a compatible container engine. +Docker Desktop would work fine of course. +We install [docker/cli](https://github.com/docker/cli) and [abiosoft/colima](https://github.com/abiosoft/colima) with aqua. +Please confirm that the docker command works. + +```sh +docker version +``` + +## Format with prettier + +https://prettier.io/ + +```sh +npm i -g prettier +``` + +```sh +prettier -w registry.yaml +``` + +## cmdx s - Scaffold configuration and test it in containers + +`cmdx s ` generates a configuration file `pkgs//registry.yaml` and a test data file `pkgs//pkg.yaml`, and tests them in containers. +It gets data from GitHub Releases by GitHub API. +By default, it gets all releases, so it takes a bit long time if the repository has a lot of releases. +[`cmdx s` isn't perfect, but you must use it when you add new packages.](#use-cmdx-s-definitely) + +## cmdx t - Test a package in containers + +`cmdx t []` tests a package in containers. +If the branch name is `feat/`, you can omit the argument ``. +`cmdx t` copies files `pkgs//{pkg.yaml,registry.yaml}` in containers and test them. +If the test succeeds, `registry.yaml` is updated. + +## cmdx rm - Remove containers + +`cmdx rm` removes containers. +`cmdx s` and `cmdx t` reuse containers, but if you want to test packages in clean environment, you can do it by removing containers. + +## cmdx rmp - Remove an installed package from containers + +`cmdx rmp []` removes an installed package from containers. +If the branch name is `feat/`, you can omit the argument ``. +It runs `aqua rm ` and removes `aqua-checksums.json` in containers. +This task is useful when you want to test packages in clean environment. + +## cmdx gr - Update `registry.yaml` + +`cmdx gr` merges `pkgs/**/registry.yaml` and updates [registry.yaml](https://github.com/aquaproj/aqua-registry/blob/main/registry.yaml). +Please don't edit [registry.yaml](https://github.com/aquaproj/aqua-registry/blob/main/registry.yaml) directly. +When you edit `pkgs/**/registry.yaml`, please run `cmdx gr` to reflect the update to `registry.yaml` in the repository. + +## cmdx con - Connect to a container + +`cmdx con [] []` connect to a given container. +`cmdx s` and `cmdx t` tests packages in containers. +`cmdx con` is useful to look into the trouble in containers. +By default, `` is `linux` and `` is CPU architecture of your machine. + +## Code Auto-generation + +Writing configuration files for each package from scratch is difficult and has quality issues. +Therefore, commands for auto-generating code are provided. +When adding a new package, always use this command. +Code written manually from scratch is not quality assured, so Pull Requests will not be accepted. +However, code auto-generation is not perfect and often generates incomplete code. +In that case, you need to manually fix the generated code. + +aqua supports various package types, but currently auto-generation mainly supports only `github_release` and `cargo`. +When generating code for other packages like `http` package, specify `-l 1` to generate only a template and write the rest manually. + +```sh +cmdx s -l 1 "" +``` + +## GitHub Access Token + +Development tools execute GitHub API to get lists of GitHub Releases and assets. +It works without an access token, but the possibility of hitting API rate limits increases. +Hitting API rate limits can prevent normal code generation or cause tests to fail. +You can pass an access token through environment variables `GITHUB_TOKEN` or `AQUA_GITHUB_TOKEN`. +If these environment variables are not set, it will try to get an access token using the `gh auth token` command. +No special permissions are needed as it only reads public repository resources. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 00000000000..fbaf762780b --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,41 @@ +# Trouble shooting + +## `cmdx new` fails to push a commit to the origin + +:::info +We removed `cmdx new` from the guide. +You can still use `cmdx new`, but if you have any trouble with `cmdx new`, you can create a pull request without `cmdx new`. +[Please see the changelog for details.](changelog.md#why-did-we-remove-cmdx-new-from-the-guide) +::: + +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 + +```console +$ 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](https://github.com/aquaproj/aqua-registry/fork). +2. Check remote repositories. + +```sh +git remote -v +``` + +3. Please fix `origin`. + +```sh +git remote set-url origin https://github.com/ +``` + +4. Please set `upstream` if necessary. + +```sh +git remote add upstream https://github.com/aquaproj/aqua-registry +``` From 9cb70ae41247f6d07c3658a4c7959bcafa4e1faf Mon Sep 17 00:00:00 2001 From: "autofix-ci[bot]" <114827586+autofix-ci[bot]@users.noreply.github.com> Date: Thu, 26 Feb 2026 10:09:36 +0000 Subject: [PATCH 2/2] [autofix.ci] apply automated fixes --- .claude/skills/fetch-doc/SKILL.md | 2 +- .claude/skills/review/SKILL.md | 2 +- AGENTS.md | 2 +- docs/add_package.md | 1 + docs/error_handling.md | 6 +++--- docs/guide.md | 12 ++++++------ docs/pkg_yaml.md | 4 ++-- docs/registry_yaml.md | 4 ++-- 8 files changed, 17 insertions(+), 16 deletions(-) diff --git a/.claude/skills/fetch-doc/SKILL.md b/.claude/skills/fetch-doc/SKILL.md index dadd0fa3b0a..a5fe33479db 100644 --- a/.claude/skills/fetch-doc/SKILL.md +++ b/.claude/skills/fetch-doc/SKILL.md @@ -16,4 +16,4 @@ git pull origin main ``` Then please see .ai/aqua/website/docs. -Especially, about the registry settings, please see .ai/aqua/website/docs/reference/registry-config/*.md. +Especially, about the registry settings, please see .ai/aqua/website/docs/reference/registry-config/\*.md. diff --git a/.claude/skills/review/SKILL.md b/.claude/skills/review/SKILL.md index 9d27506bb64..7ac701d1698 100644 --- a/.claude/skills/review/SKILL.md +++ b/.claude/skills/review/SKILL.md @@ -3,4 +3,4 @@ name: review-change description: Review changes. Use this skill when adding or changing pkgs/**/*.yaml --- -Please review pkgs/**/*.yaml according to CONTRIBUTING.md +Please review pkgs/\*_/_.yaml according to CONTRIBUTING.md diff --git a/AGENTS.md b/AGENTS.md index 2ad75bc5757..f49f4cd6b53 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -15,7 +15,7 @@ git pull origin main ``` Then please see .ai/aqua/website/docs. -Especially, about the registry settings, please see .ai/aqua/website/docs/reference/registry-config/*.md. +Especially, about the registry settings, please see .ai/aqua/website/docs/reference/registry-config/\*.md. JSON Schema: diff --git a/docs/add_package.md b/docs/add_package.md index ad6204e9000..93c9940fa51 100644 --- a/docs/add_package.md +++ b/docs/add_package.md @@ -142,6 +142,7 @@ e.g. ```yaml all_assets_filter: not (Asset contains "static") ``` + ::: 1. Create `aqua-generate-registry.yaml` by `aqua gr --init` command: diff --git a/docs/error_handling.md b/docs/error_handling.md index 5bc872b39fe..4081b0c9c6d 100644 --- a/docs/error_handling.md +++ b/docs/error_handling.md @@ -93,9 +93,9 @@ By default, it's the same as `name`. For gh, since the path is different, you need to specify `src`. ```yaml - files: - - name: gh - src: gh_{{trimV .Version}}_{{.OS}}_{{.Arch}}/bin/gh +files: + - name: gh + src: gh_{{trimV .Version}}_{{.OS}}_{{.Arch}}/bin/gh ``` https://github.com/aquaproj/aqua-registry/blob/dc98ca0c3314ae3cface74556a295a4cb0a95918/pkgs/cli/cli/registry.yaml#L7-L9 diff --git a/docs/guide.md b/docs/guide.md index 114468f53f3..95f97fbe372 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -33,13 +33,13 @@ One characteristic to identify if code is old is how `version_constraint` and `v In the new style, it basically looks like this: ```yaml - version_constraint: "false" # Root version_constraint is "false" - version_overrides: - - version_constraint: semver("<= 0.1.0") # Version constraints use <, <= not >, >= (basically <=) - # ... +version_constraint: "false" # Root version_constraint is "false" +version_overrides: + - version_constraint: semver("<= 0.1.0") # Version constraints use <, <= not >, >= (basically <=) + # ... + # ... + - version_constraint: "true" # End with "true" for latest version configuration # ... - - version_constraint: "true" # End with "true" for latest version configuration - # ... ``` In the old style, `version_overrides` is often not defined. diff --git a/docs/pkg_yaml.md b/docs/pkg_yaml.md index 4ac429a8145..6a301f41de2 100644 --- a/docs/pkg_yaml.md +++ b/docs/pkg_yaml.md @@ -1,6 +1,6 @@ -# Style Style Guide of pkgs/**/pkg.yaml +# Style Style Guide of pkgs/\*\*/pkg.yaml -## What's pkgs/**/pkg.yaml for? +## What's pkgs/\*\*/pkg.yaml for? `pkgs/**/pkg.yaml` are test data. `pkgs/**/pkg.yaml` are used to test if packages can be installed properly. diff --git a/docs/registry_yaml.md b/docs/registry_yaml.md index 54d7662b9f4..e3253c1389d 100644 --- a/docs/registry_yaml.md +++ b/docs/registry_yaml.md @@ -1,4 +1,4 @@ -# Style Guide of pkgs/**/registry.yaml +# Style Guide of pkgs/\*\*/registry.yaml ## Tool Naming Convention @@ -21,7 +21,7 @@ Packages hosted outside GitHub should have naming that distinguishes them from G Platforms other than GitHub like GitLab are not actively supported, but some are supported as http type packages. [GitLab uses `gitlab.com/`.](https://github.com/aquaproj/aqua-registry/tree/main/pkgs/gitlab.com) -## YAML Language Server Comment is necessary at the top of pkgs/**/registry.yaml +## YAML Language Server Comment is necessary at the top of pkgs/\*\*/registry.yaml ```yaml # yaml-language-server: $schema=https://raw.githubusercontent.com/aquaproj/aqua/main/json-schema/registry.json