From 168ebf28a6774026725572a847d9e70d3a645a11 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A5rten=20Svantesson?= Date: Mon, 23 Dec 2024 10:12:06 +0100 Subject: [PATCH 1/3] docs: proposal for improving templating of apps from quickstarts and packs related to jenkins-x/jx#1839 jenkins-x/jx#1849 --- .../gotemplate_for_quickstarts/README.md | 57 +++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 proposals/gotemplate_for_quickstarts/README.md diff --git a/proposals/gotemplate_for_quickstarts/README.md b/proposals/gotemplate_for_quickstarts/README.md new file mode 100644 index 0000000..5312854 --- /dev/null +++ b/proposals/gotemplate_for_quickstarts/README.md @@ -0,0 +1,57 @@ +--- +title: Use go templating for quickstarts and packs +linktitle: Use go templating for quickstart +description: Proposal for improving templating of apps from quickstarts and packs +type: docs +weight: 80 +--- + +# Problem: The templating ability in quickstarts are very limited + +Currently only a very limited number of fixed strings are replaced in files in a quickstart and the +selected pack: + +- `REPLACE_ME_APP_NAME` +- `REPLACE_ME_GIT_PROVIDER` +- `REPLACE_ME_ORG` +- `REPLACE_ME_DOCKER_REGISTRY_ORG` + +The format of the inserted strings are also fixed to lower case. + +# Proposal + +Introduce configuration of the templating. The file .jx/gotemplate.yaml is read in a quickstart +repository would configure the templating. Just the presense of this file (with the correct +apiVersion and kind) would enable go template support. To reduce the risk for interference with go +templating of k8s resources and for other purposes the delimiters would by default be '[[' and ']]' +instead of the default '{{' and '}}'. But the use of other delimiters should possible to configure. + +I propose that also a pack could have a .jx/gotemplate.yaml, which would control the templating of +the pack. + +With this enabled for example `REPLACE_ME_APP_NAME` could be replaced with `[[ .AppName ]]`. A +typical case where a greater flexibility is needed is to accomodate conventions for casing in +different languages. While that could be accomodated with basic go template string functions I +propose that the functions of https://docs.gomplate.ca/ are included by default to alleviate this +task. + +Configuration options for gotemplate can be added to .spec of gotemplate.yaml. + +There are more information known to jx project that could be in quickstarts. If for example the java +version where exposed the need for multiple packs for different java version could probably be +eliminated. + +I also propose support for adding custom values. This could be done in a similar way as it was done +in the apps functionality of Jenkins X 2, where the json schema for a helm chart +(values.schema.json) where used to prompt the user for missing values. + +# Drawbacks + +Even though the point of this is to make quickstarts and packs more flexible care must be taken not +to overuse templating so maintaining the quickstarts and packs become difficult. + +# Fixes + +jenkins-x/jx#1839 + +jenkins-x/jx#1849 \ No newline at end of file From 97859ff506738c0425ebc1c078f235e9238a54d6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A5rten=20Svantesson?= Date: Wed, 8 Jan 2025 12:36:57 +0100 Subject: [PATCH 2/3] fix: wording --- proposals/gotemplate_for_quickstarts/README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/proposals/gotemplate_for_quickstarts/README.md b/proposals/gotemplate_for_quickstarts/README.md index 5312854..65f9b4e 100644 --- a/proposals/gotemplate_for_quickstarts/README.md +++ b/proposals/gotemplate_for_quickstarts/README.md @@ -20,11 +20,11 @@ The format of the inserted strings are also fixed to lower case. # Proposal -Introduce configuration of the templating. The file .jx/gotemplate.yaml is read in a quickstart -repository would configure the templating. Just the presense of this file (with the correct +Introduce configuration of the templating. If the file .jx/gotemplate.yaml exists in a quickstart +repository it is read and used to configure the templating. Just the presense of this file (with the correct apiVersion and kind) would enable go template support. To reduce the risk for interference with go templating of k8s resources and for other purposes the delimiters would by default be '[[' and ']]' -instead of the default '{{' and '}}'. But the use of other delimiters should possible to configure. +instead of the default '{{' and '}}'. But the use of other delimiters should be possible to configure. I propose that also a pack could have a .jx/gotemplate.yaml, which would control the templating of the pack. @@ -54,4 +54,4 @@ to overuse templating so maintaining the quickstarts and packs become difficult. jenkins-x/jx#1839 -jenkins-x/jx#1849 \ No newline at end of file +jenkins-x/jx#1849 From 570cf50a0bde7778945f4c601fa74005d9ca83be Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A5rten=20Svantesson?= Date: Mon, 13 Jan 2025 18:16:40 +0100 Subject: [PATCH 3/3] fix: add more suggestions to proposal --- .../gotemplate_for_quickstarts/README.md | 34 +++++++++++++++++-- 1 file changed, 31 insertions(+), 3 deletions(-) diff --git a/proposals/gotemplate_for_quickstarts/README.md b/proposals/gotemplate_for_quickstarts/README.md index 65f9b4e..b05f452 100644 --- a/proposals/gotemplate_for_quickstarts/README.md +++ b/proposals/gotemplate_for_quickstarts/README.md @@ -20,6 +20,8 @@ The format of the inserted strings are also fixed to lower case. # Proposal +## Improved templating + Introduce configuration of the templating. If the file .jx/gotemplate.yaml exists in a quickstart repository it is read and used to configure the templating. Just the presense of this file (with the correct apiVersion and kind) would enable go template support. To reduce the risk for interference with go @@ -41,9 +43,35 @@ There are more information known to jx project that could be in quickstarts. If version where exposed the need for multiple packs for different java version could probably be eliminated. -I also propose support for adding custom values. This could be done in a similar way as it was done -in the apps functionality of Jenkins X 2, where the json schema for a helm chart -(values.schema.json) where used to prompt the user for missing values. +## Custom values + +I also propose support for adding custom values. Somehow the quickstart / pack should have +requirements on values for the user to fill in. The types of input items should (at least) be +boolean, select, multi select and in text format. + +Fields could be defined as optional based on values already inputed by user. For example if a user +opts to enable database support they should be asked for more datails. + +This could be done in a similar way as it was done in the apps functionality of Jenkins X 2, where +the json schema for a helm chart (values.schema.json) where used to prompt the user for missing +values. + +## UI neutral + +We currently only have a terminal UI to create an application. It would be preferable to build the new +functionality so alternative UIs (ie web) are feasable. + +## Use ska? + +A templating tool/library that support some of these things already is +https://github.com/gchiesa/ska/. It only seem to support asking for text values. On the other hand +it also supports updating an application from a quickstart. + +It does support multiple templates for one app, which we need (quickstart and pack). + +## Build UI with huh? + +A library to gather information from the user is https://github.com/charmbracelet/huh. # Drawbacks