Contributing to ACME Portal¶

Thank you for your interest in contributing to the ACME Portal VS Code extension! This guide will help you get started with development and contributing.

Development Setup¶

Prerequisites¶

Node.js (version 18.x or 20.x)
npm (comes with Node.js)
VS Code (version 1.97.0 or later)
Git (for version control)

Getting Started¶

Fork and Clone

git clone https://github.com/your-username/acme-portal.git
cd acme-portal

Install Dependencies
```
npm install
```
Open in VS Code
```
code .
```

Development Workflow¶

Running the Extension¶

Press F5 in VS Code to launch the Extension Development Host
This opens a new VS Code window with your extension loaded
Make changes to the code and reload the window to test changes

Available Scripts¶

Command	Description
`npm run compile`	Compile TypeScript to JavaScript
`npm run watch`	Watch for changes and auto-compile
`npm run lint`	Run ESLint for code quality
`npm run test`	Run the test suite
`npm run package`	Build production bundle with webpack
`npm run knip`	Check for unused dependencies

Debugging¶

Set breakpoints in your TypeScript code
Use the Debug Console in the Extension Development Host
Check the Output panel → "ACME Portal" for extension logs
Use the Developer Tools (Help → Toggle Developer Tools)

Code Style and Standards¶

ESLint Configuration¶

The project uses ESLint with TypeScript support. Run linting with:

npm run lint

Code Formatting¶

Use 2 spaces for indentation
Follow TypeScript best practices
Add JSDoc comments for public APIs
Use meaningful variable and function names

File Organization¶

src/
├── extension.ts          # Main extension entry point
├── flowTreeProvider.ts   # Tree view implementation
├── commands/            # Command implementations
├── models/             # Data models and interfaces
├── utils/              # Utility functions
└── test/               # Test files

Testing¶

Running Tests¶

npm run test

This runs tests in a headless VS Code environment using the @vscode/test-cli framework.

Writing Tests¶

Place test files in the src/test/ directory
Use the .test.ts suffix for test files
Follow the existing test patterns:

import * as assert from 'assert';
import * as vscode from 'vscode';

suite('Extension Test Suite', () => {
  test('Sample test', () => {
    assert.strictEqual([1, 2, 3].indexOf(5), -1);
    assert.strictEqual([1, 2, 3].indexOf(0), -1);
  });
});

Test Categories¶

Unit Tests: Test individual functions and classes
Integration Tests: Test extension commands and VS Code integration
End-to-End Tests: Test complete workflows

Contributing Guidelines¶

Before You Start¶

Check existing issues for similar problems or features
Open an issue to discuss major changes before implementing
Make sure tests pass before submitting changes

Making Changes¶

Create a Branch

git checkout -b feature/your-feature-name

Make Your Changes
Write clean, well-documented code
Add tests for new functionality
Update documentation as needed

Test Your Changes

npm run lint
npm run test
npm run compile
npm run check-release-notes  # Validate release notes entry

Add Release Notes Entry
Open CHANGELOG.md
Add your change to the [Unreleased] section
Format: - **Feature Name**: Description (#PR_NUMBER)
See Release Notes Process below

Commit Your Changes

git add .
git commit -m "feat: add your feature description"

Commit Message Format¶

We follow conventional commit format:

feat: - New features
fix: - Bug fixes
docs: - Documentation changes
refactor: - Code refactoring
test: - Test additions or changes
chore: - Maintenance tasks

Examples: - feat: add flow comparison command - fix: resolve tree view refresh issue - docs: update API reference

Pull Request Process¶

Push Your Branch

git push origin feature/your-feature-name

Create Pull Request
Use a descriptive title
Fill out the PR template
Reference related issues
Add screenshots for UI changes
Address Review Feedback
Respond to comments
Make requested changes
Push updates to the same branch

Documentation¶

Updating Documentation¶

When making changes that affect users or developers:

README.md: Update if installation or basic usage changes
CHANGELOG.md: Add entries for all user-facing changes
docs/: Update relevant documentation pages
Code Comments: Add or update JSDoc comments

Documentation Style¶

Use clear, concise language
Include code examples where helpful
Keep screenshots up to date
Link to related documentation

Release Notes Process¶

Every pull request must include a release notes entry in CHANGELOG.md.

For complete guidelines, examples, and validation details, see the Release Notes Process in the main contributing guide.

Release Process¶

Version Management¶

We use semantic versioning (semver): - MAJOR.MINOR.PATCH - Increment MAJOR for breaking changes - Increment MINOR for new features - Increment PATCH for bug fixes

Automated Release Process¶

Releases are fully automated through GitHub Actions. No manual CHANGELOG.md editing required!

Update Version
```
npm version patch  # or minor/major
```

Create and Push Tag

git push origin main
git push origin --tags

Automated Workflow The release workflow automatically:
Runs comprehensive tests across multiple platforms and VS Code versions
Packages and validates the extension
Extracts release notes from the [Unreleased] section in CHANGELOG.md
Creates GitHub release with extracted release notes
Publishes to VS Code Marketplace (when VSCE_PAT secret is configured)
🆕 Updates CHANGELOG.md by moving [Unreleased] content to new version section
🆕 Commits updated CHANGELOG.md back to the main branch

New Developer Experience¶

Before (manual process):

# Developers had to manually edit CHANGELOG.md
# 1. Move [Unreleased] content to version section
# 2. Clear [Unreleased] section
# 3. Commit changes
git add CHANGELOG.md
git commit -m "Update CHANGELOG for 1.2.3"
git tag v1.2.3
git push origin v1.2.3

After (automated process):

# Developers just create the tag - automation handles everything else
git tag v1.2.3
git push origin v1.2.3
# ✅ GitHub Actions automatically updates CHANGELOG.md and commits it back

This eliminates manual steps and reduces the chance of release documentation errors.

Getting Help¶

Resources¶

Community¶

GitHub Issues: For bugs and feature requests
GitHub Discussions: For questions and general discussion
Code Reviews: Learn from PR feedback and reviews

Development Tips¶

Use VS Code's Extension Development Host for testing
Check the Output panel for debugging information
Use breakpoints liberally during development
Test on different operating systems when possible
Keep dependencies up to date but test thoroughly

Code of Conduct¶

Please note that this project follows a Code of Conduct. By participating, you are expected to:

Be respectful and inclusive
Welcome newcomers and help them learn
Focus on constructive feedback
Respect different viewpoints and experiences

Recognition¶

Contributors will be recognized in: - The CHANGELOG.md file - GitHub's contributor graph - Release notes for significant contributions

Thank you for contributing to ACME Portal! 🚀