HowTo: Revert to an Older Version

Something broke. A feature you relied on changed. A workflow that was smooth yesterday now stumbles. An update that should have made things better made them worse.

It happens. And when it does, you need to get back to a version that works -- fast. This guide walks you through reverting the SPECLAN VS Code Extension to a previous version, keeping it there, and making sure we hear about the problem so it gets fixed.

When to Revert

You might want to revert if a recent update:

Introduced a bug that blocks your workflow
Changed or removed behavior you depend on
Causes compatibility issues with your VS Code version or project setup
Feels unstable compared to the version you were on before

Reverting is a temporary measure -- a way to unblock yourself while the issue is addressed. It is not a permanent solution. We will cover how to report the problem so you can safely return to the latest version once a fix is released.

Step 1: Find the Version You Want

Before reverting, figure out which version to go back to.

Check your update history

If you are not sure which version you were running before the update, look at the SPECLAN Changelog on the VS Code Marketplace. Each release lists what changed. Find the version just before the change that caused your problem.

Check your currently installed version

Open the Extensions sidebar (Ctrl+Shift+X on Windows/Linux, Cmd+Shift+X on macOS), find SPECLAN, and look at the version number displayed next to the extension name.

Step 2: Revert to an Older Version

VS Code has built-in support for installing previous versions of any extension. No external downloads needed.

Option A: Use the Extensions UI (Recommended)

Open Extensions (Ctrl+Shift+X / Cmd+Shift+X)
Find SPECLAN in your installed extensions (type @installed speclan in the search bar)
Right-click the SPECLAN extension
Select Install Another Version...
A list of all previously published versions appears -- pick the one you want
VS Code installs the selected version and prompts you to reload

After the reload, you are running the older version.

Option B: Use the Command Line

If you prefer the terminal, VS Code's CLI can install a specific version directly:

code --install-extension DigitalDividend.speclan-vscode-extension@0.9.2 --force

Replace 0.9.2 with the version number you want. The --force flag ensures the downgrade proceeds even though a newer version is already installed.

To confirm what version is now installed:

code --list-extensions --show-versions | grep speclan

Option C: Install From a VSIX File

If you have a .vsix package file (for example, from a direct download or a team-shared archive):

Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
Run Extensions: Install from VSIX...
Select the .vsix file

Or from the terminal:

code --install-extension path/to/speclan-0.9.2.vsix

Installing from a VSIX file automatically disables auto-update for that extension, which means you will not be pushed back to the latest version unexpectedly.

Step 3: Prevent Auto-Update

By default, VS Code auto-updates extensions to the latest version. After reverting, you almost certainly want to stop that from happening -- otherwise your next restart could silently undo the downgrade.

Pin the SPECLAN extension

Open Extensions (Ctrl+Shift+X / Cmd+Shift+X)
Right-click SPECLAN
Uncheck Auto Update in the context menu

This disables auto-update for SPECLAN only. All other extensions continue to update normally.

Alternative: Disable auto-update globally

If you prefer to control all extension updates manually:

Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
Run Disable Auto Update for All Extensions

Or set it in your VS Code settings:

{
  "extensions.autoUpdate": false
}

You can re-enable auto-update at any time by reversing these steps.

Step 4: Report the Problem

Reverting gets you unblocked, but it does not fix the underlying issue. Reporting the problem helps us fix it for everyone -- including you, so you can safely return to the latest version.

What to include in your report

The version that caused the problem (the one you reverted from)
The version you reverted to (the one that works)
What went wrong -- describe the behavior you experienced, ideally with steps to reproduce
What you expected -- describe how it worked in the version you reverted to

Where to report

GitHub Issues: github.com/speclan/speclan/issues -- the primary channel for bug reports
Email: If you prefer not to use GitHub, reach out via the contact information on speclan.net

The more detail you provide, the faster the fix.

Things to Keep in Mind

Compatibility with your specifications

SPECLAN specification files are plain Markdown with YAML frontmatter. Older extension versions can generally read specifications created by newer versions without issues. However, if a newer version introduced a new frontmatter field or entity type, an older version may ignore those additions.

Your specification files themselves are never modified by a version change. They remain exactly as they are in your project directory.

Compatibility with VS Code

Older extension versions may not support the very latest VS Code release if it introduced breaking API changes. If you experience issues after reverting, try checking the extension's changelog for minimum VS Code version requirements.

Missing fixes and features

While running an older version, you will not benefit from bug fixes, security patches, or new features released after that version. This is the trade-off. Revert to get unblocked now, but plan to return to the latest version once the problem is resolved.

Returning to the Latest Version

When the issue that caused you to revert has been fixed in a new release:

Open Extensions (Ctrl+Shift+X / Cmd+Shift+X)
Right-click SPECLAN
Re-enable Auto Update (if you disabled it)
Click Update to install the latest version, or simply restart VS Code

You are back on the latest version with the fix included.

Quick Reference

Task	How
Revert via UI	Right-click extension > Install Another Version...
Revert via CLI	`code --install-extension DigitalDividend.speclan-vscode-extension@x.y.z --force`
Revert via VSIX	Command Palette > Extensions: Install from VSIX...
Pin version (prevent auto-update)	Right-click extension > uncheck Auto Update
Check installed version	`code --list-extensions --show-versions \| grep speclan`
Return to latest	Right-click extension > Update