Skip to content
v3.0.0archived

Working With Wheels

Contributing to Wheels VS Code Extension

Contributing to Wheels VS Code Extension

Section titled “Contributing to Wheels VS Code Extension”

Repository

Section titled “Repository”

The Wheels VS Code Extension is located in the main Wheels repository at tools/vscode-ext/:

GitHub Repository

Development Setup

Section titled “Development Setup”

Prerequisites

Section titled “Prerequisites”
  • Node.js (version 14 or higher)
  • VS Code
  • Git

Initial Setup

Section titled “Initial Setup”

  1. Clone the Wheels repository:

    Terminal window
    git clone https://github.com/wheels-dev/wheels.git
    cd wheels/tools/vscode-ext

  2. Install VS Code Extension CLI globally (optional, for packaging):

    Terminal window
    npm install -g vsce

Extension Structure

Section titled “Extension Structure”
tools/vscode-ext/
├── src/                      # Extension source code
│   ├── extension.js          # Extension functions
├── snippets/                 # Code snippets for Wheels
│   ├── wheels-api.json       # Contains wheels all API functions
│   ├── wheels.code-snippets  # Model-specific snippets
├── assets/                   # Extension assets (icons, etc.)
│   ├── wheels_logo.jpg       # Wheels Logo for extension
├── package.json              # Extension manifest and configuration
├── README.md                 # Extension documentation
├── CHANGELOG.md              # Version history
└── LICENSE                   # License

Making Changes

Section titled “Making Changes”

Adding New Snippets

Section titled “Adding New Snippets”
  1. Navigate to the appropriate snippet file in /snippets/
  2. Add your snippet following the existing pattern: 
    "functionName": {
      "prefix": "functionName",
      "body": [
        "functionName(${1:param} = \"${2:value}\")"
      ],
      "description": "Function description"
    }

Updating Function Documentation

Section titled “Updating Function Documentation”
  1. Edit files in /src/ directory
  2. Update hover documentation and parameter information
  3. Ensure examples are accurate and helpful

Modifying Extension Configuration

Section titled “Modifying Extension Configuration”
  1. Update package.json for:
    • Version numbers
    • New file type support
    • Activation events
    • Contribution points

Testing Your Changes

Section titled “Testing Your Changes”

Local Testing

Section titled “Local Testing”
  1. Open the extension directory in VS Code
  2. Press F5 to launch Extension Development Host
  3. Test your changes in the new VS Code window
  4. Verify:
    • Snippets work correctly
    • Hover documentation displays properly
    • Completions appear as expected
    • No errors in Developer Console

Building and Testing VSIX

Section titled “Building and Testing VSIX”
  1. Package the extension:
    Terminal window
    vsce package
  2. Install the generated .vsix file locally
  3. Test in a real world environment

Code Quality Standards

Section titled “Code Quality Standards”

Snippet Guidelines

Section titled “Snippet Guidelines”
  • Use meaningful prefixes that match function names
  • Provide both basic and full parameter versions where applicable
  • Include helpful default values
  • Add clear descriptions

Documentation Standards

Section titled “Documentation Standards”
  • Keep hover documentation concise but comprehensive
  • Include practical examples
  • Document all parameters with types
  • Maintain consistency with Wheels documentation

Upgrading and Maintenance

Section titled “Upgrading and Maintenance”

Keeping Snippets Current

Section titled “Keeping Snippets Current”
  1. Monitor Wheels framework releases for new functions
  2. Update existing snippets when function signatures change
  3. Remove deprecated functions
  4. Test against latest Wheels version

Version Management

Section titled “Version Management”
  1. Follow semantic versioning (MAJOR.MINOR.PATCH)
  2. Update package.json version
  3. Document changes in CHANGELOG.md
  4. Tag releases appropriately

Compatibility Testing

Section titled “Compatibility Testing”

Test extension with:

  • Latest stable VS Code version
  • Different CFML file types (.cfm, .cfc)
  • Various Wheels project structures
  • Multiple operating systems if possible

Contributing Process

Section titled “Contributing Process”

Follow the standard Wheels contribution process:

  1. Open an Issue: Before making changes, open an issue in the issue tracker describing your proposed changes
  2. Get Approval: Wait for core team approval before starting development
  3. Fork and Branch: Create a feature branch from develop
  4. Make Changes: Implement your changes following the guidelines above
  5. Test Thoroughly: Test your changes locally and with packaged VSIX
  6. Submit Pull Request: Create a pull request to the develop branch, before creating a PR, please also review Contributing to Wheels and Submitting Pull Requests guide
  7. Code Review: Address any feedback from the core team

Pull Request Guidelines

Section titled “Pull Request Guidelines”
  • Reference the issue number in your PR description
  • Include clear commit messages
  • Test against multiple VS Code versions if possible
  • Update CHANGELOG.md for user-facing changes
  • Ensure no breaking changes without proper deprecation

Reporting Issues

Section titled “Reporting Issues”

Found a bug or have a feature request for the VS Code extension?

Report Issues

When reporting extension-specific issues, please include:

  • VS Code version
  • Extension version (found in Extensions panel)
  • Wheels framework version
  • Operating system
  • Steps to reproduce the issue
  • Expected vs. actual behavior
  • Any error messages from Developer Console

Release Process

Section titled “Release Process”

Extension releases follow the main Wheels release cycle:

  1. Changes are merged to develop branch
  2. During Wheels release preparation, extension version is updated
  3. Extension is packaged and tested
  4. VSIX file will be generated at our side and tested
  5. Extension may be published to VS Code Marketplace after proper testing

Support

Section titled “Support”

For help with extension development:

Edit this page on GitHub