docs: R021

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] <domain> [<version>]`
+
+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 <domain> <function> --local -- <args>
+```
+
+This results in `<recipe> 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 <domain> <function> -- <args>
+```
+
+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 turns out, 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`

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":