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] 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