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

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 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

Creating Releases¶

Releases are automated through GitHub Actions:

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

Create Tag

git push origin main
git push origin --tags

Automated Process
CI runs tests across platforms
Extension is packaged and validated
GitHub release is created
VS Code Marketplace publishing (when configured)

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! 🚀