Merge pull request #24 from marcitqualab/main

Fix template options and improved documentation

.github/actions/smoke-test/action.yaml

@@ -9,7 +9,7 @@ runs:
   steps:
     - name: Checkout main
       id: checkout_release
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
 
     - name: Build template
       id: build_template

.github/workflows/release.yaml

@@ -7,7 +7,7 @@ jobs:
     if: ${{ github.ref == 'refs/heads/main' }}
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: "Publish Templates"
         uses: devcontainers/action@v1

.github/workflows/test-pr.yaml

@@ -8,7 +8,7 @@ jobs:
     outputs:
       templates: ${{ steps.filter.outputs.changes }}
     steps:
-      - uses: dorny/paths-filter@v2
+      - uses: dorny/paths-filter@v3
         id: filter
         with:
           filters: |
@@ -24,7 +24,7 @@ jobs:
       matrix:
         templates: ${{ fromJSON(needs.detect-changes.outputs.templates) }}
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Smoke test for '${{ matrix.templates }}'
         id: smoke_test

README.md

@@ -1,20 +1,19 @@
-# Dev Container Templates: Self Authoring Guide
+# Clojure SciCloj Dev Container Templates:
+
+> This repo provides a starting point and example for creating Clojure custom [Dev Container Templates](https://containers.dev/implementors/templates), hosted for free on SciCloj GitHub Container Registry. 
 
-> This repo provides a starting point and example for creating your own custom [Dev Container Templates](https://containers.dev/implementors/templates), hosted for free on GitHub Container Registry.  The example in this repository follows the [Dev Container Template distribution specification](https://containers.dev/implementors/templates-distribution/).  
->
-> To provide feedback on the distribution spec, please leave a comment [on spec issue #71](https://github.com/devcontainers/spec/issues/71).
 
 ## Repo and Template Structure
 
-This repository contains a _collection_ of two Templates - `hello` and `color`. These Templates serve as simple template implementations which helps containerize the project. Similar to the [`devcontainers/templates`](https://github.com/devcontainers/templates) repo, this repository has a `src` folder.  Each Template has its own sub-folder, containing at least a `devcontainer-template.json` and `.devcontainer/devcontainer.json`. 
+This repository contains a _collection_ of Templates. These Templates serve as simple template implementations which helps containerize the local development environment and package projects. Similar to the [`devcontainers/templates`](https://github.com/devcontainers/templates) repo, this repository has a `src` folder.  Each Template has its own sub-folder, containing at least a `devcontainer-template.json` and `.devcontainer/devcontainer.json`. 
 
 ```
 ├── src
-│   ├── color
+│   ├── basecloj
 │   │   ├── devcontainer-template.json
 │   │   └──| .devcontainer
 │   │      └── devcontainer.json
-│   ├── hello
+│   ├── scicloj
 │   │   ├── devcontainer-template.json
 │   │   └──| .devcontainer
 │   │      ├── devcontainer.json
@@ -24,77 +23,33 @@ This repository contains a _collection_ of two Templates - `hello` and `color`.
 │   │   └──| .devcontainer
 │   │      └── devcontainer.json
 ├── test
-│   ├── color
+│   ├── basecloj
 │   │   └── test.sh
-│   ├── hello
+│   ├── scicloj
 │   │   └── test.sh
 │   └──test-utils
 │      └── test-utils.sh
 ...
 ```
 
-### Options
-
-All available options for a Template should be declared in the `devcontainer-template.json`. The syntax for the `options` property can be found in the [devcontainer Template json properties reference](https://containers.dev/implementors/templates#devcontainer-templatejson-properties).
-
-For example, the `color` Template provides three possible options (`red`, `gold`, `green`), where the default value is set to "red".
-
-```jsonc
-{
-    // ...
-    "options": {
-        "favorite": {
-            "type": "string",
-            "description": "Choose your favorite color."
-            "proposals": [
-                "red",
-                "gold",
-                "green"
-            ],
-            "default": "red"
-        }
-    }
-}
-```
-
-An [implementing tool](https://containers.dev/supporting#tools) will use the `options` property from [the documented Dev Container Template properties](https://containers.dev/implementors/templates#devcontainer-templatejson-properties) for customizing the Template. See [option resolution example](https://containers.dev/implementors/templates#option-resolution-example) for details.
-
 ## Distributing Templates
 
-**Note**: *Allow GitHub Actions to create and approve pull requests* should be enabled in the repository's `Settings > Actions > General > Workflow permissions` for auto generation of `src/<template>/README.md` per Template (which merges any existing `src/<template>/NOTES.md`).
-
 ### Versioning
 
 Templates are individually versioned by the `version` attribute in a Template's `devcontainer-template.json`. Templates are versioned according to the semver specification. More details can be found in [the Dev Container Template specification](https://containers.dev/implementors/templates-distribution/#versioning).
 
 ### Publishing
 
-> NOTE: The Distribution spec can be [found here](https://containers.dev/implementors/templates-distribution/).  
->
-> While any registry [implementing the OCI Distribution spec](https://github.com/opencontainers/distribution-spec) can be used, this template will leverage GHCR (GitHub Container Registry) as the backing registry.
-
 Templates are source files packaged together that encode configuration for a complete development environment.
 
-This repo contains a GitHub Action [workflow](.github/workflows/release.yaml) that will publish each template to GHCR.  By default, each Template will be prefixed with the `<owner/<repo>` namespace.  For example, the two Templates in this repository can be referenced by an [implementing tool](https://containers.dev/supporting#tools) with:
+This repo contains a GitHub Action [workflow](.github/workflows/release.yaml) that will publish each template to GHCR:
 
 ```
-ghcr.io/devcontainers/template-starter/color:latest
-ghcr.io/devcontainers/template-starter/hello:latest
+ghcr.io/scicloj/devcontainer-templates/basecloj:latest
+ghcr.io/scicloj/devcontainer-templates/scicloj:latest
 ```
 
-The provided GitHub Action will also publish a third "metadata" package with just the namespace, eg: `ghcr.io/devcontainers/template-starter`. This contains information useful for tools aiding in Template discovery.
-
-'`devcontainers/template-starter`' is known as the template collection namespace.
-
-### Marking Template Public
-
-For your Template to be used, it currently needs to be available publicly. By default, OCI Artifacts in GHCR are marked as `private`. 
-
-To make them public, navigate to the Template's "package settings" page in GHCR, and set the visibility to 'public`. 
-
-```
-https://github.com/users/<owner>/packages/container/<repo>%2F<templateName>/settings
-```
+The provided GitHub Action will also publish a third "metadata" package with just the namespace, eg: `ghcr.io/scicloj/devcontainer-templates`. This contains information useful for tools aiding in Template discovery.
 
 ### Adding Templates to the Index
 

src/basecloj/.devcontainer/Dockerfile

@@ -1,4 +1,5 @@
-FROM clojure:${templateOption:imageTag}
+ARG BASE_IMAGE=temurin-21-tools-deps-jammy
+FROM clojure:${BASE_IMAGE}
 
 ARG USERNAME=vscode
 ARG USER_UID=1000

src/basecloj/.devcontainer/devcontainer.json

@@ -5,6 +5,7 @@
 	"build": {
 		"dockerfile": "Dockerfile",
 		"args": {
+			"BASE_IMAGE": "${templateOption:imageTag}",
 			"USERNAME": "${localEnv:USER}"
 		}
 	},

src/basecloj/NOTES.md

@@ -0,0 +1,40 @@
+# Minimal devcontainer with LTS JAVA, official Clojure and clj tools
+
+This template set up a minimal devcontainer environment for new Clojure projects.
+
+# Quickstart
+
+Required: Install DevContainer VSCode extension and run the command. `(Shift+Crtl+P) 'Dev Containers: Install devcontainer CLI'`
+
+1. Open a folder in vscode for the new project empty project.
+
+2. Create the new devcontainer configuration files. On a new terminal run the command:
+
+```bash
+devcontainer templates apply --workspace-folder . \
+--template-id ghcr.io/scicloj/devcontainer-templates/basecloj:latest
+
+# Optionally, add another line to select the base image 
+\
+--template-args '{"imageTag": temurin-8-tools-deps-jammy"
+```
+>  See the [devcontainer-template.json](devcontainer-template.json) for a list of options.
+
+ 
+3. `(Shift+Crtl+P) 'Dev Containers: Rebuild and Reopen in Container'`
+
+4. After the devcontainer build you have a ful Clojure dev environment with all the tools.
+
+    a. [Start the Calva repl](https://calva.io/getting-started/)
+
+    b. Create a new app, lib, template and more: 
+    * Read [deps-new](https://github.com/seancorfield/deps-new)
+    * Read [clj-new docs](https://github.com/seancorfield/clj-new) 
+
+> Note: Open a new 'bash' terminal in the devcontainer. The default terminal is 'sh' but open the arrow next to the plus sign in the terminal panel and select 'bash' type terminal.
+
+## Customization
+
+* Choose other base images from the imageTag list of [devcontainer-template.json](devcontainer-template.json) 
+
+* Install more features in devcontainer: https://containers.dev/features

src/basecloj/README.md

@@ -1,31 +1,56 @@
 
+# Minimal devcontainer with LTS JAVA, official Clojure and clj tools (basecloj)
 
+This template set up a minimal devcontainer environment for new Clojure projects.
 
 ## Options
 
 | Options Id | Description | Type | Default Value |
 |-----|-----|-----|-----|
+| imageTag | Tag of official Clojure image | string | temurin-21-tools-deps-jammy |
 
->Note: comming soon 
+# Minimal devcontainer with LTS JAVA, official Clojure and clj tools
 
-# A minimal devcontainer with JAVA, Clojure and minimal clj tools
-
-It sets up a minimal dev container environment with green fields minimal tools for Clojure.
+This template set up a minimal devcontainer environment for new Clojure projects.
 
 # Quickstart
 
-0. Install [devcontainer cli](https://github.com/devcontainers/cli)
-1. Run `devcontainer templates apply -t ghcr.io/scicloj/devcontainer-templates/basecloj` to create a devcontainer setup
-   with default settings in your current directoty
-2. Open folder with VSCode / devcontainer / devpod / Codespaces and trigger/wait for container build
-3. [Start the Calva repl](https://calva.io/getting-started/)
+Required: Install DevContainer VSCode extension and run the command. `(Shift+Crtl+P) 'Dev Containers: Install devcontainer CLI'`
+
+1. Open a folder in vscode for the new project empty project.
+
+2. Create the new devcontainer configuration files. On a new terminal run the command:
+
+```bash
+devcontainer templates apply --workspace-folder . \
+--template-id ghcr.io/scicloj/devcontainer-templates/basecloj:latest
+
+# Optionally, add another line to select the base image 
+\
+--template-args '{"imageTag": temurin-8-tools-deps-jammy"
+```
+>  See the [devcontainer-template.json](devcontainer-template.json) for a list of options.
+
+ 
+3. `(Shift+Crtl+P) 'Dev Containers: Rebuild and Reopen in Container'`
 
+4. After the devcontainer build you have a ful Clojure dev environment with all the tools.
 
-4. Create a new app, lib, template and more: 
+    a. [Start the Calva repl](https://calva.io/getting-started/)
+
+    b. Create a new app, lib, template and more: 
     * Read [deps-new](https://github.com/seancorfield/deps-new)
     * Read [clj-new docs](https://github.com/seancorfield/clj-new) 
 
+> Note: Open a new 'bash' terminal in the devcontainer. The default terminal is 'sh' but open the arrow next to the plus sign in the terminal panel and select 'bash' type terminal.
+
 ## Customization
-5. Install more features in devcontainer: https://containers.dev/features
+
+* Choose other base images from the imageTag list of [devcontainer-template.json](devcontainer-template.json) 
+
+* Install more features in devcontainer: https://containers.dev/features
+
 
 ---
+
+_Note: This file was auto-generated from the [devcontainer-template.json](https://github.com/marcitqualab/devcontainer-templates/blob/main/src/basecloj/devcontainer-template.json).  Add additional notes to a `NOTES.md`._

src/basecloj/devcontainer-template.json

@@ -1,9 +1,9 @@
 {
     "id": "basecloj",
-    "version": "1.0.0",
-    "name": "Base clojure development environment",
-    "description": "A devcontainer template with the minimum clojure tools and configuration, this template is intended to create new greenfield clojure project that should be further customised on specific project needs. ",
-    "documentationURL": "https://github.com/scicloj/devcontainer-templates/tree/main/src/basecloj",
+    "version": "1.0.1",
+    "name": "Minimal devcontainer with LTS JAVA, official Clojure and clj tools",
+    "description": "This template set up a minimal devcontainer environment for new Clojure projects.",
+    "documentationURL": "https://github.com/scicloj/devcontainer-templates/tree/main/src/basecloj/NOTES.md",
     "licenseURL": "https://github.com/scicloj/devcontainer-templates/blob/main/LICENSE",
     "options": {
         "imageTag": {

src/scicloj/README.md

@@ -7,7 +7,7 @@ A devcontainer template supporting Clojure datascience with R and python interop
 
 | Options Id | Description | Type | Default Value |
 |-----|-----|-----|-----|
-| imageTag | Tag of officlai Clojure image | string | temurin-21-tools-deps-1.11.3.1456-jammy |
+| imageTag | Tag of official Clojure image | string | temurin-21-tools-deps-1.11.3.1456-jammy |
 
 # A template project featuring a devcontainer setup for Datascience with Clojure using several libraries from [scicloj](https://scicloj.github.io/)
 
@@ -91,4 +91,4 @@ My `setup-ide.sh` configures Doom Emacs with my personal configuration.
 
 ---
 
-_Note: This file was auto-generated from the [devcontainer-template.json](https://github.com/scicloj/devcontainer-templates/blob/main/src/scicloj/devcontainer-template.json).  Add additional notes to a `NOTES.md`._
+_Note: This file was auto-generated from the [devcontainer-template.json](https://github.com/marcitqualab/devcontainer-templates/blob/main/src/scicloj/devcontainer-template.json).  Add additional notes to a `NOTES.md`._