Migrate templates-hub to Velocity syntax #22

New Issue

2026-01-03T23:39:46Z

KofTwentyTwo commented

2026-01-03 23:39:46 +00:00

(Migrated from github.com)

Part of #12

User Story

As a qctl user, I want the official templates in templates-hub to use Velocity syntax so that I can create projects with the new template engine.

Design

Templates to Migrate

Template	Description
`qqq-web-api`	Web API with Javalin middleware
`qqq-cli-tool`	Command-line tool with Picocli
`qqq-batch`	Batch processing application
`qqq-full-stack`	Full-stack with React frontend

Migration Steps Per Template

Update template.yaml to schema v2
Convert Handlebars syntax to Velocity in all files
Add computed variables for derived values
Add transforms for package path relocation
Test with qctl qqq init

Syntax Conversion Examples

Before (Handlebars):

package {{packageName}};

public class {{pascalCase appName}}App {
    private static final String NAME = "{{appName}}";
}

After (Velocity):

package $packageName;

public class ${str.pascal($appName)}App {
    private static final String NAME = "$appName";
}

Directory Structure

Before:

template/
  src/main/java/com/example/{{projectName}}/

After:

template/
  src/main/java/com/example/template/  # Static path

# In template.yaml:
transforms:
  - type: move
    from: "src/main/java/com/example/template"
    to: "src/main/java/${packagePath}"

Files to Create/Modify

Repository	File	Action
templates-hub	`qqq-web-api/template.yaml`	Migrate to v2
templates-hub	`qqq-web-api/template/*/.java`	Convert syntax
templates-hub	`qqq-cli-tool/template.yaml`	Migrate to v2
templates-hub	`qqq-cli-tool/template/*/.java`	Convert syntax
templates-hub	`qqq-batch/template.yaml`	Migrate to v2
templates-hub	`qqq-full-stack/template.yaml`	Migrate to v2

Implementation Tasks

Create migration checklist for each template
Update qqq-web-api manifest to v2 schema
Convert all qqq-web-api template files to Velocity
Add computed variables (packagePath, appClassName)
Add transforms for directory relocation
Test qqq-web-api end-to-end
Repeat for qqq-cli-tool
Repeat for qqq-batch
Repeat for qqq-full-stack
Update templates-hub README with Velocity syntax guide
Create template authoring guide

Acceptance Criteria

All templates use Velocity syntax
All templates have v2 manifests
qctl qqq init <template> works for all templates
Generated projects compile successfully
Package paths are correctly transformed
Template authoring documentation updated

Part of #12 ## User Story As a **qctl user**, I want the official templates in templates-hub to use Velocity syntax so that I can create projects with the new template engine. ## Design ### Templates to Migrate | Template | Description | |----------|-------------| | `qqq-web-api` | Web API with Javalin middleware | | `qqq-cli-tool` | Command-line tool with Picocli | | `qqq-batch` | Batch processing application | | `qqq-full-stack` | Full-stack with React frontend | ### Migration Steps Per Template 1. Update `template.yaml` to schema v2 2. Convert Handlebars syntax to Velocity in all files 3. Add computed variables for derived values 4. Add transforms for package path relocation 5. Test with `qctl qqq init` ### Syntax Conversion Examples **Before (Handlebars):** ```java package {{packageName}}; public class {{pascalCase appName}}App { private static final String NAME = "{{appName}}"; } ``` **After (Velocity):** ```java package $packageName; public class ${str.pascal($appName)}App { private static final String NAME = "$appName"; } ``` ### Directory Structure **Before:** ``` template/ src/main/java/com/example/{{projectName}}/ ``` **After:** ``` template/ src/main/java/com/example/template/ # Static path # In template.yaml: transforms: - type: move from: "src/main/java/com/example/template" to: "src/main/java/${packagePath}" ``` ## Files to Create/Modify | Repository | File | Action | |------------|------|--------| | templates-hub | `qqq-web-api/template.yaml` | Migrate to v2 | | templates-hub | `qqq-web-api/template/**/*.java` | Convert syntax | | templates-hub | `qqq-cli-tool/template.yaml` | Migrate to v2 | | templates-hub | `qqq-cli-tool/template/**/*.java` | Convert syntax | | templates-hub | `qqq-batch/template.yaml` | Migrate to v2 | | templates-hub | `qqq-full-stack/template.yaml` | Migrate to v2 | ## Implementation Tasks - [ ] Create migration checklist for each template - [ ] Update `qqq-web-api` manifest to v2 schema - [ ] Convert all `qqq-web-api` template files to Velocity - [ ] Add computed variables (packagePath, appClassName) - [ ] Add transforms for directory relocation - [ ] Test `qqq-web-api` end-to-end - [ ] Repeat for `qqq-cli-tool` - [ ] Repeat for `qqq-batch` - [ ] Repeat for `qqq-full-stack` - [ ] Update templates-hub README with Velocity syntax guide - [ ] Create template authoring guide ## Acceptance Criteria - [ ] All templates use Velocity syntax - [ ] All templates have v2 manifests - [ ] `qctl qqq init <template>` works for all templates - [ ] Generated projects compile successfully - [ ] Package paths are correctly transformed - [ ] Template authoring documentation updated

KofTwentyTwo commented

2026-01-04 03:28:55 +00:00

(Migrated from github.com)

Migration verified complete:

templates-hub uses schema v2 with Velocity computed expressions ($str.replace($packageName, '.', '/'))
new-qqq-application-template already uses Velocity syntax ($variable and ${variable})
No Handlebars syntax ({{ }}) found in any template files
Tested qctl qqq init - variables render correctly, project compiles successfully

Migration verified complete: - templates-hub uses schema v2 with Velocity computed expressions (`$str.replace($packageName, '.', '/')`) - new-qqq-application-template already uses Velocity syntax (`$variable` and `${variable}`) - No Handlebars syntax (`{{ }}`) found in any template files - Tested `qctl qqq init` - variables render correctly, project compiles successfully

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: QRun-IO/qctl#22