From 95e58933351146e45c5d0bcbcefda77aae119c57 Mon Sep 17 00:00:00 2001 From: decentral1se Date: Thu, 18 Jul 2024 13:46:26 +0200 Subject: [PATCH] docs: R021 --- .../federation/resolutions/in-progress/021.md | 57 +++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 58 insertions(+) create mode 100644 docs/federation/resolutions/in-progress/021.md diff --git a/docs/federation/resolutions/in-progress/021.md b/docs/federation/resolutions/in-progress/021.md new file mode 100644 index 0000000..28304e9 --- /dev/null +++ b/docs/federation/resolutions/in-progress/021.md @@ -0,0 +1,57 @@ +--- +title: "Resolution 021" +--- + +- Topic: Budget 011: Migrate to Cobra +- Date: 18-07-2024 +- Deadline: 31-07-2024 +- Size: Large + +### Summary + +Migrate away from our current command-line dependency so `abra` usage is more predictable. The goal is to maintain feature parity with no breaking changes. The main advantage that we will get is robust and flexible handling of flags/arguments which don't depend on forcing a specific order (see [`#581`](https://git.coopcloud.tech/coop-cloud/organising/issues/581)). There are other bonuses such as built-in support for auto-completion, better handling of example usage, improved support for global flags (`--debug`) and manpage support. + +### Details (Budget 011) + +#### The problem + +The current help output of `abra app deploy` is as follows: + +`abra app deploy [command options] []` + +However, it is possible to do both of the following: + +``` +abra app deploy --chaos example.org # "before" style +abra app deploy example.org --chaos # "after" style +``` + +However, `abra app cmd` is broken if you try to use the "after" style: + +``` +abra app cmd --local -- +``` + +This results in ` doesn't have a --local function` which is a bug in the `abra` code. It tries to read the position of the arguments but `--local` is included as an argument. The bug in `abra` is due to a bug in `urfave/cli` - "after" style options appear as arguments 😱 + +The only way to use `abra app cmd` right now is using the "before" style: + +``` +abra app cmd --local -- +``` + +This means that some commands allow both "after" and "before" style and some only allow "before" style. This is a source of confusion, raised issues and frustration. + +#### The solution + +[Several](https://git.coopcloud.tech/coop-cloud/abra/pulls/404) [attempts](https://git.coopcloud.tech/coop-cloud/abra/pulls/435) have been made to upgrade `urfave/cli` to fix this behaviour. However, as it now finally runs it, it is **highly unlikely** that they will fix this upstream: [`urfave/cli#1950`](https://github.com/urfave/cli/issues/1950) [`urfave/cli#1928`](https://github.com/urfave/cli/pull/1928) (and even this proposal does not really include the desired robust flexible handling we need). + +`@decentral1se` has done a spike to confirm that [`cobra`](https://cobra.dev) handles flexible handling of arguments/flags. Those reading this proposal and wishing to try it out for themselves can take [Hugo](https://gohugo.io/) for a spin (it uses `cobra` as the underlying command-line library). + +This tool is well maintained and used by several large projects such as Hugo and Kubernetes. The library matches all functionality we require. + +#### Budget + +`@decentral1se` can carry out this work. + +Proposed budget of 15 hrs: `15 hrs * 20 = 300 EUR` diff --git a/mkdocs.yml b/mkdocs.yml index 690e757..d8d1938 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -130,6 +130,7 @@ nav: - federation/resolutions/passed/020.md - "In Progress": - federation/resolutions/in-progress/013.md + - federation/resolutions/in-progress/021.md - "Minutes": - federation/minutes/index.md - "Recently":