From 8b48f8c765ecf642fd070504cdf2827c917c8994 Mon Sep 17 00:00:00 2001 From: xynydev Date: Sun, 1 Oct 2023 15:24:06 +0300 Subject: [PATCH 1/8] docs: module working directory, style guides --- build.sh | 3 ++- modules/README.md | 18 +++++++++++++++++- 2 files changed, 19 insertions(+), 2 deletions(-) diff --git a/build.sh b/build.sh index f4eedce4b8..f93a5b3f03 100644 --- a/build.sh +++ b/build.sh @@ -23,10 +23,11 @@ run_module() { MODULE="$1" TYPE=$(echo "$MODULE" | yq '.type') if [[ "$TYPE" != "null" ]]; then + cd "$CONFIG_DIRECTORY" # If type is found, that means that the module config # has been declared inline, and thus is safe to pass to the module echo "=== Launching module of type: $TYPE ===" - bash "$MODULE_DIRECTORY/$TYPE/$TYPE.sh" "$MODULE" + bash "$MODULE_DIRECTORY/$TYPE/$TYPE.sh" "$MODULE" else # If the type is not found, that means that the module config # is in a separate file, and has to be read from it diff --git a/modules/README.md b/modules/README.md index fc9113a41a..9d444e38e4 100644 --- a/modules/README.md +++ b/modules/README.md @@ -8,6 +8,8 @@ Modules get only the configuration options given to them in the recipe.yml, not Additionally, each module has access to four environment variables, `CONFIG_DIRECTORY` pointing to the Startingpoint directory in `/usr/share/ublue-os/`, `IMAGE_NAME` being the name of the image as declared in the recipe, `BASE_IMAGE` being the URL of the container image used as the base (FROM) in the image, and `OS_VERSION` being the `VERSION_ID` from `/usr/lib/os-release`. +When running modules, the working directory is the `CONFIG_DIRECTORY`. + A helper bash function called `get_yaml_array` is exported from the main build script. ```bash # "$1" is the first cli argument, being the module configuration. @@ -22,4 +24,18 @@ All bash-based modules should start with the following lines to ensure the image ```bash #!/usr/bin/env bash set -oue pipefail -``` \ No newline at end of file +``` + +## Style directions for official modules + +### Bash + +- Start with `#!/usr/bin/env bash` and `set -oue pipefail` +- Don't print "===", this is only for encapsulating the output of _different_ modules in `build.sh` +- Print something on each step and on errors for easier debugging +- Use CAPITALIZED names for variables that are read from the configuration + +### README + +- Title should be "`type` module for startingpoint", where the name/type of the module is a noun that shows the module's purpose +- There should be a subtitle "Example configuration:", under which there should be a loosely documented yaml block showcasing each of the module's configuration options \ No newline at end of file From 4645605c6b3e3beef6c5951266f0c22fbbce372b Mon Sep 17 00:00:00 2001 From: xynydev Date: Sun, 1 Oct 2023 15:26:26 +0300 Subject: [PATCH 2/8] docs: how to refer to modules in module READMEs --- modules/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/modules/README.md b/modules/README.md index 9d444e38e4..481980eeaa 100644 --- a/modules/README.md +++ b/modules/README.md @@ -38,4 +38,5 @@ set -oue pipefail ### README - Title should be "`type` module for startingpoint", where the name/type of the module is a noun that shows the module's purpose -- There should be a subtitle "Example configuration:", under which there should be a loosely documented yaml block showcasing each of the module's configuration options \ No newline at end of file +- There should be a subtitle "Example configuration:", under which there should be a loosely documented yaml block showcasing each of the module's configuration options +- At the start of each paragraph, refer to the module using its name or with "the module", not "it" or "the script" \ No newline at end of file From 1d9e6f20ff191818dfe0dd6e5bf776aaf859fe63 Mon Sep 17 00:00:00 2001 From: xynydev Date: Sun, 1 Oct 2023 15:27:26 +0300 Subject: [PATCH 3/8] docs: chore: remove ":" from Example configuration this change should be propagated to bling --- modules/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/README.md b/modules/README.md index 481980eeaa..6488009c0d 100644 --- a/modules/README.md +++ b/modules/README.md @@ -38,5 +38,5 @@ set -oue pipefail ### README - Title should be "`type` module for startingpoint", where the name/type of the module is a noun that shows the module's purpose -- There should be a subtitle "Example configuration:", under which there should be a loosely documented yaml block showcasing each of the module's configuration options +- There should be a subtitle "Example configuration", under which there should be a loosely documented yaml block showcasing each of the module's configuration options - At the start of each paragraph, refer to the module using its name or with "the module", not "it" or "the script" \ No newline at end of file From 7e08a383c92cbf0aa82734a76b756313ba732d4f Mon Sep 17 00:00:00 2001 From: xynydev Date: Sun, 1 Oct 2023 15:32:14 +0300 Subject: [PATCH 4/8] docs: grammar recommendations --- modules/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/modules/README.md b/modules/README.md index 6488009c0d..b05836ebc0 100644 --- a/modules/README.md +++ b/modules/README.md @@ -39,4 +39,5 @@ set -oue pipefail - Title should be "`type` module for startingpoint", where the name/type of the module is a noun that shows the module's purpose - There should be a subtitle "Example configuration", under which there should be a loosely documented yaml block showcasing each of the module's configuration options -- At the start of each paragraph, refer to the module using its name or with "the module", not "it" or "the script" \ No newline at end of file +- At the start of each paragraph, refer to the module using its name or with "the module", not "it" or "the script" +- Use passive grammar when talking about the user, ie. "should be used", "can be configured", preferring references to what the module does, ie. "This module downloads the answer to the question of life, the universe and everything..." \ No newline at end of file From 2fb7aefbb631143f88dc7465bafb077cf9632be3 Mon Sep 17 00:00:00 2001 From: xynydev Date: Sun, 1 Oct 2023 16:21:23 +0300 Subject: [PATCH 5/8] docs: correct title casing in style guide --- modules/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/README.md b/modules/README.md index b05836ebc0..faf7c18bd1 100644 --- a/modules/README.md +++ b/modules/README.md @@ -37,7 +37,7 @@ set -oue pipefail ### README -- Title should be "`type` module for startingpoint", where the name/type of the module is a noun that shows the module's purpose +- Title should be "`type` Module for Startingpoint", where the name/type of the module is a noun that shows the module's purpose - There should be a subtitle "Example configuration", under which there should be a loosely documented yaml block showcasing each of the module's configuration options - At the start of each paragraph, refer to the module using its name or with "the module", not "it" or "the script" - Use passive grammar when talking about the user, ie. "should be used", "can be configured", preferring references to what the module does, ie. "This module downloads the answer to the question of life, the universe and everything..." \ No newline at end of file From 1691ad8d4f73d30fdf358b3d4f66ea003e5efdb4 Mon Sep 17 00:00:00 2001 From: xynydev Date: Sun, 1 Oct 2023 16:36:45 +0300 Subject: [PATCH 6/8] docs: yaml not yml, directions qualifier --- modules/README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/modules/README.md b/modules/README.md index faf7c18bd1..9aac8899e1 100644 --- a/modules/README.md +++ b/modules/README.md @@ -28,6 +28,8 @@ set -oue pipefail ## Style directions for official modules +These are general directions for writing official modules and their documentation to follow to keep a consistent style. Not all of these are to be mindlessly followed, especially the ones about grammar and writing style. It's good to keep these in mind if you intend to contribute back upstream, though, so that your module doesn't feel out of place. + ### Bash - Start with `#!/usr/bin/env bash` and `set -oue pipefail` @@ -39,5 +41,6 @@ set -oue pipefail - Title should be "`type` Module for Startingpoint", where the name/type of the module is a noun that shows the module's purpose - There should be a subtitle "Example configuration", under which there should be a loosely documented yaml block showcasing each of the module's configuration options + - For a YAML block, specify the language as "yaml", not "yml" (MkDocs only supports "yaml") - At the start of each paragraph, refer to the module using its name or with "the module", not "it" or "the script" -- Use passive grammar when talking about the user, ie. "should be used", "can be configured", preferring references to what the module does, ie. "This module downloads the answer to the question of life, the universe and everything..." \ No newline at end of file +- Use passive grammar when talking about the user, ie. "should be used", "can be configured", preferring references to what the module does, ie. "This module downloads the answer to the question of life, the universe and everything..." From 8596d5381e3cc8e790198d8fd8ed0f0846cba0c9 Mon Sep 17 00:00:00 2001 From: xynydev Date: Sun, 1 Oct 2023 17:06:30 +0300 Subject: [PATCH 7/8] fix: ublue-update failure when signing image --- config/scripts/signing.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/config/scripts/signing.sh b/config/scripts/signing.sh index 8affdd907b..5f0f0e3a8f 100644 --- a/config/scripts/signing.sh +++ b/config/scripts/signing.sh @@ -24,7 +24,7 @@ yq -i -o=j '.transports.docker |= + .' "$FILE" IMAGE_REF="ostree-image-signed:docker://$IMAGE_REGISTRY/$IMAGE_NAME" -printf '{\n"image-ref": "'"$IMAGE_REF"'",\n"image-default-tag": "latest"\n}' > /usr/share/ublue-os/image-info.json +printf '{\n"image-ref": "'"$IMAGE_REF"'",\n"image-tag": "latest"\n}' > /usr/share/ublue-os/image-info.json cp /usr/etc/containers/registries.d/ublue-os.yaml /usr/etc/containers/registries.d/"$IMAGE_NAME".yaml sed -i "s ghcr.io/ublue-os $IMAGE_REGISTRY g" /usr/etc/containers/registries.d/"$IMAGE_NAME".yaml From 29a0cd13b3ae82fa1dfb2d64880f4ca30f8f3aee Mon Sep 17 00:00:00 2001 From: xynydev Date: Sun, 1 Oct 2023 17:13:20 +0300 Subject: [PATCH 8/8] chore: rm deprecated fonts bling from recipe --- config/recipe.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/config/recipe.yml b/config/recipe.yml index 3dd0e51a48..7daeb74ac6 100644 --- a/config/recipe.yml +++ b/config/recipe.yml @@ -32,7 +32,6 @@ modules: - type: bling # configure what to pull in from ublue-os/bling install: - - fonts # selection of common good free fonts - justfiles # add "!include /usr/share/ublue-os/just/bling.just" # in your custom.just (added by default) or local justfile - nix-installer # shell shortcuts for determinate system's nix installers