Contributing to ol-contextmenu

First off, thank you for considering contributing to ol-contextmenu! 🎉

We love contributions from the community. Whether it's a bug report, feature request, documentation improvement, or code contribution, every contribution is valuable.

Table of Contents

• Code of Conduct
• How Can I Contribute?
• Development Setup
• Pull Request Process
• Coding Guidelines
• Testing
• Documentation

Code of Conduct

This project adheres to a Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers.

How Can I Contribute?

Reporting Bugs

Before creating bug reports, please check existing issues to avoid duplicates.

When submitting a bug report, include:

• Clear title and description
• Steps to reproduce the issue
• Expected behavior vs actual behavior
• Screenshots if applicable
• Environment details:
  • ol-contextmenu version
  • OpenLayers version
  • Browser and version
  • Operating system
• Minimal reproduction example (CodeSandbox, JSFiddle, or repository)

Suggesting Enhancements

Enhancement suggestions are welcome! Please provide:

• Clear use case - Why is this needed?
• Detailed description - What should it do?
• Examples - How would it be used?
• Alternatives considered - What other solutions did you consider?

Pull Requests

We actively welcome pull requests!

Development Setup

Prerequisites

• Node.js: 16.x or higher
• npm: 8.x or higher
• Git

Fork and Clone

1. Fork the repository on GitHub
2. Clone your fork locally:

git clone https://github.com/YOUR_USERNAME/ol-contextmenu.git
cd ol-contextmenu

3. Add upstream remote:

git remote add upstream https://github.com/jonataswalker/ol-contextmenu.git

Install Dependencies

npm install

Development Commands

# Start development server
npm run dev

# Run tests
npm test

# Run tests in watch mode
npm run test:ui

# Run linter
npm run lint

# Fix linting issues
npm run lint:fix

# Build for production
npm run build

Project Structure

ol-contextmenu/
├── src/
│   ├── main.ts           # Main entry point
│   ├── constants.ts      # Constants and defaults
│   ├── types.ts          # TypeScript type definitions
│   ├── helpers/          # Helper functions
│   └── sass/             # Styles
├── tests/                # Test files
│   ├── *.unit.spec.ts    # Unit tests
│   └── *.browser.spec.ts # Browser tests
├── examples/             # Example implementations
├── docs/                 # Documentation
└── dist/                 # Build output (generated)

Pull Request Process

1. Create a Feature Branch

git checkout -b feature/my-new-feature
# or
git checkout -b fix/issue-description

2. Make Your Changes

• Write clean, readable code
• Follow the coding guidelines
• Add tests for new functionality
• Update documentation as needed

3. Test Your Changes

# Run all tests
npm test

# Run linter
npm run lint

# Build to ensure no errors
npm run build

All tests must pass before submitting a PR.

4. Commit Your Changes

Write clear, descriptive commit messages:

git commit -m "feat: add support for custom menu positioning

- Add new positioning API
- Update documentation
- Add tests for new feature

Fixes #123"

Commit message format:

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation changes
• test: - Adding or updating tests
• refactor: - Code refactoring
• style: - Code style changes (formatting)
• chore: - Maintenance tasks

5. Push to Your Fork

git push origin feature/my-new-feature

6. Create Pull Request

1. Go to the original repository
2. Click "New Pull Request"
3. Select your fork and branch
4. Fill out the PR template:
   • Describe your changes
   • Reference related issues
   • Add screenshots if applicable
   • Check all boxes in the PR checklist

7. Code Review

• Maintainers will review your PR
• Address any requested changes
• Keep the PR up to date with the main branch

8. Merge

Once approved, a maintainer will merge your PR. Congratulations! 🎉

Coding Guidelines

TypeScript

• Use TypeScript for all new code
• Export types for public APIs
• Avoid any - use proper types
• Document complex types with comments

// ✅ Good
interface MenuOptions {
    /** Width of the menu in pixels */
    width?: number;
    /** Default menu items */
    items?: Item[];
}

// ❌ Avoid
function doSomething(data: any) { ... }

Code Style

We use ESLint for code style. Run npm run lint:fix to auto-fix issues.

Key points:

• Indentation: 4 spaces
• Semicolons: Required
• Quotes: Single quotes for strings
• Line length: 100 characters max
• Naming:
  • camelCase for variables and functions
  • PascalCase for classes and types
  • UPPER_CASE for constants

Best Practices

• Keep functions small and focused
• Avoid side effects where possible
• Use descriptive names for variables and functions
• Comment complex logic but avoid obvious comments
• Handle errors gracefully
• Validate inputs for public APIs

Testing

We use Vitest for testing with both unit and browser tests.

Writing Tests

1. Place tests in the tests/ directory
2. Name test files: *.spec.ts or *.test.ts
3. Use descriptive test names

describe('ContextMenu', () => {
    it('should open menu on right-click', async () => {
        // Arrange
        const contextmenu = new ContextMenu();
        map.addControl(contextmenu);

        // Act
        dispatchContextMenu(viewport);
        await new Promise(resolve => setTimeout(resolve, 150));

        // Assert
        expect(contextmenu.isOpen()).toBe(true);
    });
});

Test Coverage

• Aim for high coverage (>90%)
• Test edge cases and error conditions
• Test TypeScript types where applicable

Running Specific Tests

# Run specific file
npx vitest run tests/instance.unit.spec.ts

# Run tests matching pattern
npx vitest run --grep "should open menu"

Documentation

Updating Docs

When adding features or changing behavior:

1. Update README.md if it affects basic usage
2. Update API docs in docs/api-reference.md
3. Add examples to docs/examples.md
4. Update TypeScript docs if types changed
5. Add to CHANGELOG.md

Writing Documentation

• Be clear and concise
• Include code examples
• Explain the "why" not just the "how"
• Use proper markdown formatting
• Keep it up to date

Getting Help

Need help with your contribution?

• 💬 Ask questions in your PR or issue
• 📖 Read the docs in the /docs directory
• 🔍 Search existing issues and PRs
• 👥 Reach out to maintainers

Recognition

Contributors are recognized in:

• Contributors Graph
• Release notes (for significant contributions)

Thank you for contributing to ol-contextmenu! ❤️