@@ -8,7 +8,7 @@ This document describes how to integrate the new Nickel-based template system in
88
99### Three-Layer Project Generator Pattern
1010
11- ```
11+ ``` text
1212Domain (Config structs)
1313 ↓
1414Context Builder (PrometheusContext, TrackerContext, etc.)
@@ -57,7 +57,7 @@ Create a new `NickelProjectGenerator` trait and implementations **alongside** ex
5757
5858#### New Module Structure
5959
60- ```
60+ ``` text
6161src/infrastructure/templating/
6262├── nickel/ # NEW: Nickel-based rendering
6363│ ├── mod.rs
@@ -419,6 +419,7 @@ impl ProjectGenerator {
419419### 1. Script Availability
420420
421421The Nickel rendering scripts must be in ` provisioning/scripts/ ` :
422+
422423- ` nickel-render-yaml.sh `
423424- ` nickel-render-toml.sh `
424425- ` nickel-render-hcl.sh `
@@ -430,6 +431,7 @@ Check existence and provide helpful error messages if missing.
430431### 2. Template Path Resolution
431432
432433Templates are in ` provisioning/templates/ ` relative to project root:
434+
433435``` rust
434436let template_path = ProjectRoot :: path ()
435437 . join (" provisioning/templates/prometheus/config.ncl" );
@@ -440,7 +442,8 @@ Ensure paths work both in development and when crate is used as a dependency.
440442### 3. Error Handling Strategy
441443
442444Nickel rendering errors should be clear:
443- ```
445+
446+ ``` text
444447Error: Nickel template evaluation failed for prometheus/config.ncl:
445448 Reason: Failed to import ../values/config.ncl: File not found
446449
@@ -450,6 +453,7 @@ Error: Nickel template evaluation failed for prometheus/config.ncl:
450453### 4. Context vs Nickel Values
451454
452455** Tera approach** (existing):
456+
453457``` rust
454458let context = PrometheusContext {
455459 scrape_interval : " 30s" . to_string (),
@@ -460,6 +464,7 @@ renderer.render(&context)?;
460464```
461465
462466** Nickel approach** (new):
467+
463468``` rust
464469// No explicit context needed - Nickel imports from:
465470// - provisioning/values/config.ncl (user configuration)
@@ -474,17 +479,20 @@ The configuration comes from Nickel's import system, not passed as Rust struct.
474479### 5. Gradual Migration Path
475480
476481** Option A: Parallel Systems** (recommended)
482+
477483- Both Tera and Nickel implementations coexist
478484- Each template type migrates independently
479485- No breaking changes to existing code
480486- Transition over multiple releases
481487
482- ** Option B: Progressive Replacement**
488+ #### Option B: Progressive Replacement
489+
483490- Start with simple templates (Prometheus)
484491- Graduate to complex ones (Tracker)
485492- Remove Tera when all templates migrated
486493
487- ** Option C: Feature Flag**
494+ #### Option C: Feature Flag
495+
488496- Add ` nickel-templates ` Cargo feature
489497- Enable/disable per use case
490498- Production uses Tera, new deployments use Nickel
@@ -579,6 +587,7 @@ pub fn render_nickel_template(
579587```
580588
581589Then use it in ProjectGenerator:
590+
582591``` rust
583592pub fn render_prometheus_nickel (& self ) -> Result <(), NickelRenderError > {
584593 render_nickel_template (
@@ -594,6 +603,7 @@ pub fn render_prometheus_nickel(&self) -> Result<(), NickelRenderError> {
594603### Unit Tests
595604
596605Test script execution and error handling:
606+
597607``` rust
598608#[test]
599609fn it_should_execute_nickel_render_script () {
@@ -610,6 +620,7 @@ fn it_should_handle_missing_script() {
610620### Integration Tests
611621
612622Test actual Nickel rendering:
623+
613624``` rust
614625#[test]
615626fn it_should_render_prometheus_identically_to_tera () {
@@ -622,6 +633,7 @@ fn it_should_render_prometheus_identically_to_tera() {
622633### E2E Tests
623634
624635Test generated configs work in deployment:
636+
625637``` rust
626638#[tokio:: test]
627639async fn it_should_deploy_with_nickel_generated_config () {
@@ -634,6 +646,7 @@ async fn it_should_deploy_with_nickel_generated_config() {
634646## Summary
635647
636648This integration approach:
649+
637650- ✅ ** Non-breaking** : Nickel templates work alongside Tera
638651- ✅ ** Gradual** : Migrate one template type at a time
639652- ✅ ** Simple** : Leverages existing shell scripts
0 commit comments