Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
496 lines (383 loc) · 11.3 KB

CONTRIBUTING.md

File metadata and controls

496 lines (383 loc) · 11.3 KB

Contributing to NoteDown

Thank you for your interest in contributing to NoteDown! This guide will help you get started with development, building, and submitting changes.

📋 Table of Contents

Quick Start

# 1. Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/NoteDown.git
cd NoteDown

# 2. Set up development environment
make setup

# 3. Build and test
make dev
make test

# 4. Make your changes
# ... edit files ...

# 5. Test your changes
make fmt
make lint
make test
make build

# 6. Submit a pull request

Development Setup

Prerequisites

Environment Setup

# Automated setup (recommended)
make setup

# This will install:
# - golangci-lint for Go linting
# - npm dependencies for VSCode extension
# - vsce for extension packaging

Manual Setup (if make setup fails)

# Install Go linting tool
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v1.54.2

# Install VSCode extension dependencies
cd vscode-extension
npm install
npm install -g @vscode/vsce
cd ..

# Download Go modules
go mod download

Build System

NoteDown uses a comprehensive Makefile-based build system. See the Build System Guide for full details.

Key Build Commands

Command Purpose When to Use
make dev Development build with race detection Daily development
make build Production build for current platform Testing your changes
make test Run all tests Before committing
make lint Run linters Before committing
make fmt Format code Before committing
make clean Clean build artifacts When switching branches

Cross-Platform Testing

# Build for all platforms (takes longer)
make build-cli

# Test specific platform
GOOS=windows GOARCH=amd64 go build -o noted.exe ./cmd/noted

Development Workflow

Recommended Daily Workflow

# 1. Start with a clean state
make clean

# 2. Pull latest changes
git pull origin main

# 3. Create a feature branch
git checkout -b feature/your-feature-name

# 4. Make your changes
# ... edit files ...

# 5. Test as you go
make dev          # Quick build with race detection
./noted --help    # Test the binary

# 6. Before committing
make fmt          # Format code
make lint         # Check for issues  
make test         # Run tests
make build        # Full build
make test-build   # Test the built binary

VSCode Extension Development

# Build extension
make build-vscode

# Install for testing
# 1. Open VSCode
# 2. Ctrl+Shift+P -> "Extensions: Install from VSIX"
# 3. Select dist/notedown-vscode-X.X.X.vsix

# Development with watch mode
cd vscode-extension
npm run watch     # Rebuilds on file changes

Testing

Running Tests

# Run all tests
make test

# Run specific test suites
go test ./...                      # Go tests only
cd vscode-extension && npm test    # VSCode extension tests

# Run tests with coverage
go test -cover ./...

# Run tests in verbose mode
go test -v ./...

Writing Tests

Go Tests

  • Place test files alongside source files with _test.go suffix
  • Use table-driven tests for multiple test cases
  • Include both unit tests and integration tests
func TestFunction(t *testing.T) {
    tests := []struct {
        name     string
        input    string
        expected string
    }{
        {"basic case", "input", "expected"},
        // ... more test cases
    }
    
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            result := Function(tt.input)
            if result != tt.expected {
                t.Errorf("got %v, want %v", result, tt.expected)
            }
        })
    }
}

VSCode Extension Tests

  • Use the VSCode testing framework
  • Place tests in vscode-extension/src/test/
  • Test both unit functionality and extension integration

Testing Your Changes

Always test your changes thoroughly:

# 1. Build and basic functionality test
make build
./dist/noted --version
./dist/noted --help

# 2. Test CLI commands
./dist/noted init test-repo
cd test-repo
../dist/noted new "Test Note"
../dist/noted list
cd ..

# 3. Test VSCode extension
make build-vscode
# Install and test in VSCode

# 4. Clean up
rm -rf test-repo

Code Standards

Go Code

  • Follow Go Code Review Comments
  • Use gofmt and goimports for formatting
  • Add comments for exported functions and types
  • Handle errors appropriately
  • Use meaningful variable and function names
// Good: Descriptive function with proper error handling
func CreateNote(title, content string) (*Note, error) {
    if title == "" {
        return nil, fmt.Errorf("title cannot be empty")
    }
    
    note := &Note{
        Title:   title,
        Content: content,
        Created: time.Now(),
    }
    
    if err := note.Validate(); err != nil {
        return nil, fmt.Errorf("invalid note: %w", err)
    }
    
    return note, nil
}

TypeScript Code (VSCode Extension)

  • Follow TypeScript Style Guide
  • Use ESLint for linting
  • Add JSDoc comments for functions
  • Use proper TypeScript types
/**
 * Creates a new note in the workspace
 * @param title The note title
 * @param content The note content
 * @returns Promise resolving to the created note
 */
async function createNote(title: string, content: string): Promise<Note> {
    if (!title.trim()) {
        throw new Error('Title cannot be empty');
    }
    
    const note: Note = {
        title: title.trim(),
        content: content.trim(),
        created: new Date(),
    };
    
    return await noteService.create(note);
}

Documentation

  • Update documentation when adding features
  • Include practical examples in documentation
  • Update the changelog for significant changes
  • Add inline code comments for complex logic

Release Process

For Maintainers

The release process is largely automated through the build system:

1. Prepare Release

# Ensure everything is clean and tested
make clean
make test
make lint
make release

# Verify release artifacts
ls -la dist/
cat dist/checksums.sha256

2. Version Management

Version is automatically detected from vscode-extension/package.json:

{
  "version": "0.2.0"
}

To release a new version:

  1. Update the version in vscode-extension/package.json
  2. Commit the version change
  3. Create a git tag: git tag -a v0.2.0 -m "Release v0.2.0"
  4. Push: git push origin v0.2.0

3. GitHub Release

# Create complete release with checksums
make checksums

# Upload to GitHub releases:
# - All .tar.gz files
# - All .zip files  
# - .vsix file
# - checksums.sha256

4. CI/CD Pipeline

The project supports GitHub Actions for automated releases:

# .github/workflows/release.yml
name: Release
on:
  push:
    tags: ['v*']
jobs:
  build-and-release:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-go@v4
      with:
        go-version: '1.21'
    - name: Build releases
      run: make checksums
    - name: Create Release
      uses: softprops/action-gh-release@v1
      with:
        files: |
          dist/*.tar.gz
          dist/*.zip
          dist/*.vsix
          dist/checksums.sha256

Release Checklist

  • All tests pass (make test)
  • Code is properly formatted (make fmt)
  • No linting issues (make lint)
  • Version updated in package.json
  • Documentation updated
  • Changelog updated
  • Release builds successfully (make release)
  • Checksums generated (make checksums)
  • Git tag created and pushed
  • GitHub release created with all artifacts

Submitting Changes

Before Submitting

# Pre-submission checklist
make clean
make fmt
make lint
make test
make build
make test-build

# Ensure no build artifacts are committed
git status

Pull Request Process

  1. Fork the repository and create your branch from main
  2. Make your changes following the development workflow
  3. Add tests for new functionality
  4. Update documentation as needed
  5. Run the full test suite and ensure it passes
  6. Submit a pull request with:
    • Clear title describing the change
    • Detailed description of what was changed and why
    • Link to any related issues
    • Screenshots for UI changes

Pull Request Template

## Description
Brief description of changes and motivation.

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update
- [ ] Build system change

## Testing
- [ ] Tests added/updated
- [ ] All tests pass locally
- [ ] Tested on multiple platforms (if applicable)

## Documentation
- [ ] Documentation updated
- [ ] README updated (if needed)
- [ ] Comments added for complex code

## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] No unnecessary debug/console statements
- [ ] Build artifacts not included in commit

Getting Help

Development Questions

Build Issues

Code Review Process

  • All submissions require review before merging
  • Reviews focus on code quality, testing, and documentation
  • Address reviewer feedback promptly
  • Squash commits before final merge if requested

Coding Guidelines Summary

Commit Messages

Use conventional commit format:

type(scope): description

feat(cli): add new note creation command
fix(vscode): resolve extension loading issue
docs(build): update cross-platform build guide

Branch Naming

  • feature/description - New features
  • fix/description - Bug fixes
  • docs/description - Documentation updates
  • refactor/description - Code refactoring

Code Organization

  • Keep functions focused and small
  • Use meaningful names for variables and functions
  • Add comments for complex business logic
  • Group related functionality together
  • Follow existing project structure

Thank you for contributing to NoteDown! 🚀

Your contributions help make NoteDown a better tool for everyone. If you have questions about contributing, don't hesitate to ask in the discussions or open an issue.

← Back to README | Build System Guide →