Standardise Abra Terminology #36

New Issue

roxxers · 2021-08-02T22:34:51Z

roxxers commented

2021-08-02 22:34:51 +00:00

We use app and recipe interchangably? I find this sorta confusing esp when coding. I think we could work on the naming of things for this. Related to #13 I guess.

3wordchant commented

2021-08-03 00:44:12 +00:00

Yep, consistency would be good. We couldn't think of a better names starting out, but "recipe" seems to make sense to people.

Before:

instance, e.g. wordpress_foo_com.env = "app"
definition, e.g. wordpress = "type" (interally) and "app" in the UI and the docs

I think now:

instance, e.g. wordpress_foo_com.env = "app"
definition, e.g. wordpress = "recipe"

Yep, consistency would be good. We couldn't think of a better names starting out, but "recipe" seems to make sense to people. Before: - instance, e.g. `wordpress_foo_com.env` = "app" - definition, e.g. wordpress = "type" (interally) and "app" in the UI and the docs I think now: - instance, e.g. `wordpress_foo_com.env` = "app" - definition, e.g. wordpress = "recipe"

decentral1se commented

2021-08-03 09:48:18 +00:00

Thanks for raising this, also on my mind! The idea of the recipe didn't really sit well with me in the code for exactly the reason you mentioned. I think we just need to firm up some stuff and we're good.

On the command-line now, we have app new (is it an app?) which takes a <type> argument (is it a type of an app?) which all makes use of what is referred to in another sub-command as a recipe.

Our top-level concepts for end-users are 1. Apps 2. Recipes 3. Servers which is pretty good. 3 is a magic number.

"Recipes" are analogous to "Packages" in other projects. "I installed the Gitea package" in other projects means "I deployed the Gitea app" in our project, I think. Because there are two types of people here, the people who deploy apps and the people who package them for Co-op Cloud (those may overlap but it is good to separate the concerns for the concepts).

Guessing at some steps:

abra app new ... <recipe>
changed all TYPE= to RECIPE= in the .env files
expand the meaning of an app to be the following in the docs:
1. an upstream libre software project and published container (foo/bar:v1.0.0)
2. a recipe which is a bunch of configuraton files (compose.yml)
Use the magic 3 as top-level types in the codebase (see below)

But for the general case, you only need to care about recipes if you are cooking one up. Otherwise, everything is an app! In this sense, a recipe is kind of an implementation detail.

Can we organise the code to match the magic 3 @roxxers? We can break out into other types but these will always find their place as a field in these 3 top-level types. When we write code, we work mostly with these types and this mental model.

type App struct {...}
type Recipe struct {...}
type Server struct {...}

I'll stop typing now but that might mean the config package becomes recipe?

Thanks for raising this, also on my mind! The idea of the recipe didn't really sit well with me in the code for exactly the reason you mentioned. I think we just need to firm up some stuff and we're good. On the command-line now, we have `app new` (is it an app?) which takes a `<type>` argument (is it a type of an app?) which all makes use of what is referred to in another sub-command as a `recipe`. Our top-level concepts for end-users are 1. Apps 2. Recipes 3. Servers which is pretty good. [3 is a magic number](https://www.youtube.com/watch?v=aU4pyiB-kq0). "Recipes" are analogous to "Packages" in other projects. "I installed the Gitea package" in other projects means "I deployed the Gitea app" in our project, I think. Because there are two types of people here, the people who deploy apps and the people who package them for Co-op Cloud (those may overlap but it is good to separate the concerns for the concepts). Guessing at some steps: - `abra app new ... <recipe>` - changed all `TYPE=` to `RECIPE=` in the `.env` files - expand the meaning of an app to be the following in the docs: 1. an upstream libre software project and published container (`foo/bar:v1.0.0`) 2. a recipe which is a bunch of configuraton files (`compose.yml`) - Use the magic 3 as top-level types in the codebase (see below) But for the general case, you only need to care about recipes if you are cooking one up. Otherwise, everything is an app! In this sense, a recipe is kind of an implementation detail. Can we organise the code to match the magic 3 @roxxers? We can break out into other types but these will always find their place as a field in these 3 top-level types. When we write code, we work mostly with these types and this mental model. ``` type App struct {...} type Recipe struct {...} type Server struct {...} ``` I'll stop typing now but that might mean the `config` package becomes `recipe`?

decentral1se commented

2021-08-03 09:54:18 +00:00

(sorry I can't stop)

This could instead be: Apps, Recipes and Servers as top-level?

The libre-ness is a sub-point of an App.

The packaging format is a sub-point of a Recipe.

The container orchestrator/runtime is a sub-point of a Server.

The command-line tool is not really part of an architecture, that should stay on the same page I guess, can be dropped down into another section, I think. But yeah, this mapping seems to hold in the docs as well?

(sorry I can't stop) ![image](/attachments/16297023-5689-487c-882f-b474e0206855) This could instead be: Apps, Recipes and Servers as top-level? The libre-ness is a sub-point of an App. The packaging format is a sub-point of a Recipe. The container orchestrator/runtime is a sub-point of a Server. The command-line tool is not really part of an architecture, that should stay on the same page I guess, can be dropped down into another section, I think. But yeah, this mapping seems to hold in the docs as well?

image.png

37 KiB

3wordchant commented

2021-08-03 11:23:06 +00:00

On the command-line now, we have app new (is it an app?) which takes a <type> argument (is it a type of an app?) which all makes use of what is referred to in another sub-command as a recipe.

I think this is because we implemented app new before we'd come up with "recipe", and never went back and changed it.

The "magic 3" sounds great. And your migration steps look A+.

> On the command-line now, we have app new (is it an app?) which takes a `<type>` argument (is it a type of an app?) which all makes use of what is referred to in another sub-command as a recipe. I think this is because we implemented `app new` before we'd come up with "recipe", and never went back and changed it. The "magic 3" sounds great. And your migration steps look A+.

roxxers commented

2021-08-04 00:33:46 +00:00

I'll stop typing now but that might mean the config package becomes recipe?

Not exactly. Partly the package could be split but I am going go overhual this so that the config is loaded when needed and is persistant. So this area of th ecode will change a lot.

> I'll stop typing now but that might mean the config package becomes recipe? Not exactly. Partly the package could be split but I am going go overhual this so that the config is loaded when needed and is persistant. So this area of th ecode will change a lot.

decentral1se commented

2021-08-11 10:21:15 +00:00

We could do an inventory of the public APIs of each file and try to plan out interfaces that match names all together one day. https://github.com/princjef/gomarkdoc is really handy for this to get a good overview.

decentral1se added the

design

label 2021-09-03 10:25:27 +00:00

decentral1se added this to the (deleted) milestone 2021-09-04 21:03:19 +00:00

decentral1se referenced this issue from a commit

2021-09-04 22:15:01 +00:00

refactor: clear up app/recipe usage

decentral1se commented

2021-09-06 09:58:30 +00:00

I've done some reorganising of the code and renaming and such and I think I have a pretty good handle of converging all the things into this magic 3 in the very near future! We'll have a number of changes to make in other places but we'll get there. Just a quick update from my side.

decentral1se self-assigned this 2021-09-06 15:36:25 +00:00

decentral1se commented

2021-09-07 08:11:42 +00:00

I'm calling this done. When you work in the recipe commands, you just recipe := internal.ValidateRecipe(c) and then work with it. And then when you're in the app commands, you just app := internal.ValidateApp(c) and then you work with that. I think we have the guardrails up now. There are lots of ways it can be improved but anyway, moving along.

I'm calling this done. When you work in the recipe commands, you just `recipe := internal.ValidateRecipe(c)` and then work with it. And then when you're in the app commands, you just `app := internal.ValidateApp(c)` and then you work with that. I think we have the guardrails up now. There are lots of ways it can be improved but anyway, moving along.

decentral1se closed this issue

2021-09-07 08:11:42 +00:00

Sign in to join this conversation.

3 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: toolshed/abra#36