Contributing to Code Context Notes

October 17, 2025 · View on GitHub

Thanks for your interest in contributing! This document provides guidelines and instructions for contributing to the project.

Code of Conduct

Be respectful, inclusive, and constructive. We're all here to build something useful together.

Getting Started

Prerequisites

Node.js 16+ and npm
VSCode 1.80.0 or higher
Git
TypeScript knowledge

Development Setup

Fork and clone the repository

git clone https://github.com/jnahian/code-context-notes
cd code-context-notes

Install dependencies
```
npm install
```
Compile TypeScript
```
npm run compile
```
Run in development mode
- Open the project in VSCode
- Press F5 to launch Extension Development Host
- Test your changes in the new window

Project Structure

code-context-notes/
├── src/
│   ├── extension.ts           # Extension entry point
│   ├── noteManager.ts          # Core note management logic
│   ├── storageManager.ts       # File I/O and markdown handling
│   ├── commentController.ts    # VSCode comment UI integration
│   ├── codeLensProvider.ts     # CodeLens indicators
│   ├── contentHashTracker.ts   # Content tracking and hashing
│   ├── gitIntegration.ts       # Git username detection
│   ├── types.ts                # TypeScript interfaces
│   └── test/
│       ├── runTest.ts          # Test runner for integration tests
│       ├── runUnitTests.ts     # Test runner for unit tests
│       └── suite/              # Test files
├── docs/                       # Documentation
├── out/                        # Compiled JavaScript (generated)
├── .code-notes/                # Example notes (gitignored)
└── package.json                # Extension manifest

Development Workflow

Making Changes

Create a feature branch

git checkout -b feature/your-feature-name

Make your changes
- Write clean, readable code
- Follow existing code style
- Add JSDoc comments for public APIs
- Update tests as needed

Test your changes

# Run unit tests
npm run test:unit

# Run with coverage
npm run test:coverage

# Run all tests (requires VSCode)
npm test

Commit your changes
```
git add .
git commit -m "feat: add your feature description"
```
Use conventional commit messages:
- feat: - New feature
- fix: - Bug fix
- docs: - Documentation changes
- test: - Test changes
- refactor: - Code refactoring
- chore: - Build/tooling changes

Push and create a pull request

git push origin feature/your-feature-name

Testing Guidelines

Unit Tests

Unit tests run in pure Node.js without VSCode API:

// src/test/suite/storageManager.test.ts
import { expect } from 'chai';
import { StorageManager } from '../../storageManager';

describe('StorageManager', () => {
  it('should save and load notes', async () => {
    const storage = new StorageManager('/tmp/test');
    // ... test implementation
  });
});

Requirements:

Test all public methods
Test edge cases and error conditions
Use descriptive test names
Clean up test files in afterEach

Integration Tests

Integration tests use VSCode API and run in Extension Development Host:

// src/test/suite/noteManager.test.ts
import * as vscode from 'vscode';
import { expect } from 'chai';
import { NoteManager } from '../../noteManager';

describe('NoteManager Integration', () => {
  it('should create note in VSCode document', async () => {
    const doc = await vscode.workspace.openTextDocument({
      content: 'test content'
    });
    // ... test implementation
  });
});

Requirements:

Test VSCode API integration
Test multi-file scenarios
Test document change handling
Clean up resources in afterEach

Coverage Goals

Maintain >80% code coverage
All new features must include tests
Bug fixes should include regression tests

Code Style

Use TypeScript strict mode
Follow existing formatting (2 spaces, single quotes)
Use meaningful variable names
Keep functions focused and small
Add JSDoc comments for public APIs

Example:

/**
 * Creates a new note for the specified code range.
 * 
 * @param filePath - Absolute path to the source file
 * @param lineRange - Start and end line numbers
 * @param content - Note content in markdown format
 * @returns The created note with generated ID and metadata
 */
async createNote(
  filePath: string,
  lineRange: { start: number; end: number },
  content: string
): Promise<Note> {
  // Implementation
}

Architecture Guidelines

Core Principles

Separation of Concerns
- Storage layer handles file I/O
- Note manager handles business logic
- Controllers handle UI integration
Dependency Injection
- Pass dependencies through constructors
- Makes testing easier
- Reduces coupling
Error Handling
- Always handle errors gracefully
- Show user-friendly error messages
- Log errors for debugging
Performance
- Cache data when appropriate
- Debounce expensive operations
- Use async/await for I/O

Adding New Features

When adding a new feature:

Update types (src/types.ts) if needed
Implement core logic in appropriate manager
Add storage support if persisting data
Update UI (comment controller or CodeLens)
Add tests (unit and integration)
Update documentation (README, JSDoc)
Add configuration if user-configurable

Modifying Existing Features

When modifying existing features:

Check tests - ensure they still pass
Update tests - if behavior changed
Check dependencies - what else might break?
Update docs - if user-facing changes
Test manually - in Extension Development Host

Pull Request Process

Before Submitting

All tests pass (npm run test:unit)
Code coverage maintained or improved
No TypeScript errors (npm run compile)
Documentation updated if needed
Commit messages follow conventions
Branch is up to date with main

PR Description

Include in your PR description:

What - What does this PR do?
Why - Why is this change needed?
How - How does it work?
Testing - How did you test it?
Screenshots - If UI changes

Example:

## What
Adds support for note templates

## Why
Users requested ability to create notes from templates for common patterns

## How
- Added template configuration in settings
- Added template picker in comment UI
- Templates stored in `.code-notes/templates/`

## Testing
- Added unit tests for template loading
- Added integration tests for template picker
- Manually tested with 5 different templates

## Screenshots
[Screenshot of template picker]

Review Process

Maintainer reviews your PR
Address any feedback or requested changes
Once approved, maintainer will merge

Reporting Issues

Bug Reports

Include:

VSCode version
Extension version
Operating system
Steps to reproduce
Expected behavior
Actual behavior
Screenshots if applicable
Error messages from Developer Console

Feature Requests

Include:

Use case - what problem does it solve?
Proposed solution - how should it work?
Alternatives considered
Examples from other tools

Questions?

Open a GitHub Discussion
Check existing Issues
Read the documentation

License

By contributing, you agree that your contributions will be licensed under the MIT License.