Merge pull request #1938 from rocketstack-matt/feat/setup

rocketstack-matt · web-flow · commit aa1e3ee6d5e2 · 2025-12-09T15:39:00.000Z
feat(setup): add setup guide for keeping CALM tools up to date and update content copying script
diff --git a/advent-of-calm/home.md b/advent-of-calm/home.md
@@ -24,9 +24,9 @@ Each day from December 1st through December 24th, a new challenge unlocks. Each
 Before you begin, make sure you have:
 - Git installed
 - Node.js (18+) and npm installed
-- VSCode editor (recommended)
+- VSCode editor (106+)
 - GitHub account (recommended for portfolio sharing)
-- GitHub Copilot access (optional but helpful)
+- GitHub Copilot access
 
 ### Your First Steps
 
diff --git a/advent-of-calm/setup.md b/advent-of-calm/setup.md
@@ -0,0 +1,143 @@
+# Keeping Your CALM Tools Up to Date
+
+We make frequent updates to improve your experience with CALM. This page explains how to ensure you're always using the latest versions of all CALM tools.
+
+## CALM CLI
+
+The CALM CLI (`@finos/calm-cli`) is the core command-line tool for working with CALM architecture files.
+
+### Check Your Current Version
+
+```bash
+calm --version
+```
+
+### Update to the Latest Version
+
+To update the CALM CLI to the latest version, run:
+
+```bash
+npm install -g @finos/calm-cli
+```
+
+This will fetch and install the latest release from npm. We recommend doing this regularly, especially if you encounter any issues or want to use new features.
+
+### Verify the Update
+
+After updating, verify the new version:
+
+```bash
+calm --version
+```
+
+## CALM VS Code Extension
+
+The CALM VS Code Extension provides syntax highlighting, validation, and IntelliSense for CALM JSON files.
+
+### Check for Updates
+
+1. Open VS Code
+2. Click on the Extensions icon in the sidebar (or press `Cmd+Shift+X` / `Ctrl+Shift+X`)
+3. Search for "CALM" in your installed extensions
+4. If an update is available, you'll see an "Update" button
+
+### Enable Auto-Updates
+
+To ensure you always have the latest version:
+
+1. Open VS Code Settings (`Cmd+,` / `Ctrl+,`)
+2. Search for "extensions auto update"
+3. Set **Extensions: Auto Update** to "All Extensions" or "Only Enabled Extensions"
+
+### Manual Update
+
+If auto-update is disabled, you can manually update:
+
+1. Go to the Extensions view
+2. Find the CALM extension
+3. Click the gear icon and select "Check for Updates"
+4. Click "Update" if available
+
+## CALM Copilot Chatmode
+
+The CALM Copilot Chatmode enhances GitHub Copilot with deep knowledge of the CALM specification, making it an expert assistant for architecture authoring.
+
+### What is a Chatmode?
+
+Chatmodes are specialized configurations for GitHub Copilot Chat that provide domain-specific expertise. The CALM chatmode includes:
+- Complete CALM schema knowledge
+- Best practices for architecture modeling
+- Examples and patterns
+
+### Install or Update the Chatmode
+
+Use the CALM CLI to install or update the chatmode:
+
+```bash
+calm copilot-chatmode
+```
+
+This command will:
+- Create or update `.github/copilot-instructions.md` in your repository
+- Download the latest chatmode configuration from the CALM project
+- Ensure you have the most up-to-date CALM expertise for Copilot
+
+### Apply the Update
+
+After installing or updating the chatmode:
+
+1. **Start a new Copilot Chat session** in VS Code
+   - Close any existing chat panels
+   - Open a fresh chat session (click the Copilot chat icon or use `Cmd+Shift+I` / `Ctrl+Shift+I`)
+
+2. The updated chatmode will be active in your new chat session
+
+**Note:** You don't need to restart VS Code - just start a new chat session!
+
+## Why Keep Updated?
+
+Regular updates ensure you have:
+- **Latest features** - New capabilities and commands
+- **Bug fixes** - Resolved issues and improved stability  
+- **Better performance** - Optimizations and speed improvements
+- **Security patches** - Important security updates
+- **Updated documentation** - Accurate help and examples
+- **Schema updates** - Support for new CALM specification versions
+
+## Troubleshooting
+
+### CLI Issues
+
+If you experience issues after updating the CLI:
+
+1. Clear npm cache: `npm cache clean --force`
+2. Reinstall: `npm uninstall -g @finos/calm-cli && npm install -g @finos/calm-cli`
+3. Check Node.js version: `node --version` (Node.js 18+ recommended)
+
+### VS Code Extension Issues
+
+If the extension isn't working properly:
+
+1. Reload VS Code window
+2. Disable and re-enable the extension
+3. Uninstall and reinstall the extension
+4. Check the Output panel (View → Output → select "CALM" from dropdown)
+
+### Chatmode Issues
+
+If Copilot doesn't seem to be using the chatmode:
+
+1. Verify `.github/copilot-instructions.md` exists in your repository root
+2. Run `calm copilot-chatmode` to ensure it's up to date
+3. Start a completely new chat session (close and reopen)
+4. Ensure GitHub Copilot is active (check status bar)
+5. Make sure you're chatting from within your repository directory
+
+## Getting Help
+
+If you continue to experience issues:
+
+- Check the [CALM documentation](https://calm.finos.org)
+- Visit the [GitHub repository](https://github.com/finos/architecture-as-code)
+- Open an issue on GitHub
+
diff --git a/advent-of-calm/website/package.json b/advent-of-calm/website/package.json
@@ -8,7 +8,7 @@
     "build": "npm run copy:content && astro check && astro build",
     "preview": "astro preview",
     "astro": "astro",
-    "copy:content": "mkdir -p src/content/days && cp ../day-*.md src/content/days/ && cp ../home.md src/"
+    "copy:content": "mkdir -p src/content/days && cp ../day-*.md src/content/days/ && cp ../setup.md src/content/days/ && cp ../home.md src/"
   },
   "dependencies": {
     "@astrojs/check": "^0.9.6",
diff --git a/advent-of-calm/website/src/layouts/Layout.astro b/advent-of-calm/website/src/layouts/Layout.astro
@@ -28,6 +28,17 @@ const { title, description = "A 24-day progressive learning challenge for CALM"
       </div>
     </header>
     
+    <div class="update-banner">
+      <div class="container">
+        <div class="banner-content">
+          <span class="banner-icon">💡</span>
+          <div class="banner-text">
+            <strong>Stay Up to Date!</strong> We make frequent updates. <a href={`${import.meta.env.BASE_URL}setup/`} class="banner-link">See here</a> for how to make sure you're using the latest CALM tools.
+          </div>
+        </div>
+      </div>
+    </div>
+    
     <main>
       <div class="container">
         <slot />
@@ -100,6 +111,55 @@ const { title, description = "A 24-day progressive learning challenge for CALM"
     color: var(--color-accent);
   }
   
+  .update-banner {
+    background: linear-gradient(135deg, #007dff 0%, #0056b3 100%);
+    color: white;
+    padding: var(--spacing-md) 0;
+    box-shadow: 0 4px 6px -1px rgb(0 0 0 / 0.1);
+  }
+  
+  .banner-content {
+    display: flex;
+    align-items: flex-start;
+    gap: var(--spacing-sm);
+  }
+  
+  .banner-icon {
+    font-size: 1.5rem;
+    flex-shrink: 0;
+  }
+  
+  .banner-text {
+    flex: 1;
+    line-height: 1.6;
+  }
+  
+  .banner-text strong {
+    font-weight: 600;
+    display: inline-block;
+    margin-bottom: 0.25rem;
+  }
+  
+  .banner-text code {
+    background: rgba(255, 255, 255, 0.2);
+    color: white;
+    padding: 0.15em 0.4em;
+    border-radius: 4px;
+    font-size: 0.9em;
+    font-family: 'Consolas', 'Monaco', 'Courier New', monospace;
+  }
+  
+  .banner-link {
+    color: white;
+    text-decoration: underline;
+    font-weight: 600;
+  }
+  
+  .banner-link:hover {
+    color: rgba(255, 255, 255, 0.9);
+    text-decoration: none;
+  }
+  
   @media (max-width: 768px) {
     .logo img {
       height: 32px;
@@ -108,5 +168,17 @@ const { title, description = "A 24-day progressive learning challenge for CALM"
     .title {
       font-size: 1.2rem;
     }
+    
+    .update-banner {
+      padding: var(--spacing-sm) 0;
+    }
+    
+    .banner-icon {
+      font-size: 1.25rem;
+    }
+    
+    .banner-text {
+      font-size: 0.9rem;
+    }
   }
 </style>
diff --git a/advent-of-calm/website/src/pages/setup.astro b/advent-of-calm/website/src/pages/setup.astro
