Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
197 lines (144 loc) · 8.59 KB

CONTRIBUTING.md

File metadata and controls

197 lines (144 loc) · 8.59 KB

Contributing to Extreme Router

First off, thank you for considering contributing to Extreme Router! Your help is appreciated.

This document provides guidelines for contributing to this project. Please feel free to propose changes to this document in a pull request.

Table of Contents

How Can I Contribute?

Reporting Bugs

This section guides you through submitting a bug report for Extreme Router. Following these guidelines helps maintainers and the community understand your report, reproduce the behavior, and find related reports.

  • Use the GitHub Issues tab to create a bug report.
  • Check if the bug has already been reported by searching the issues.
  • Provide a clear and descriptive title.
  • Describe the steps to reproduce the bug with as much detail as possible. Include code snippets if applicable.
  • Explain the behavior you observed and what you expected to happen.
  • Include details about your environment (Node.js/Bun version, OS, etc.).

Suggesting Enhancements

This section guides you through submitting an enhancement suggestion for Extreme Router, including completely new features and minor improvements to existing functionality.

  • Use the GitHub Issues tab to create an enhancement suggestion.
  • Provide a clear and descriptive title.
  • Provide a step-by-step description of the suggested enhancement in as many details as possible.
  • Explain why this enhancement would be useful to most Extreme Router users.
  • Include code examples if applicable.

Your First Code Contribution

Unsure where to begin contributing to Extreme Router? You can start by looking through good first issue or help wanted issues.

Pull Requests

The process described here has several goals:

  • Maintain Extreme Router's quality.
  • Fix problems that are important to users.
  • Engage the community in working toward the best possible Extreme Router.
  • Enable a sustainable system for Extreme Router's maintainers to review contributions.

Please follow these steps to have your contribution considered by the maintainers:

  1. Follow the Development Setup instructions.
  2. Follow the Styleguides.
  3. Ensure Testing requirements are met.
  4. Submit your pull request!

Development Setup

As mentioned in the README.md#development, you'll need Bun installed.

  1. Clone the repository: 
    git clone https://github.com/liorcodev/extreme-router.git
cd extreme-router
  2. Install dependencies: 
    bun install

Styleguides

Git Commit Messages

This project aims to follow the Conventional Commits specification. This helps with automated changelog generation (as seen in CHANGELOG.MD) and makes the commit history easier to read.

Common prefixes include:

  • feat: (new feature)
  • fix: (bug fix)
  • docs: (documentation changes)
  • style: (formatting, missing semi colons, etc; no code logic change)
  • refactor: (refactoring production code)
  • test: (adding missing tests, refactoring tests; no production code change)
  • chore: (updating build tasks etc; no production code change)
  • perf: (performance improvements)

JavaScript/TypeScript Styleguide

Consistency is key. Please adhere to the established style in the codebase.

  • Formatting: All code is automatically formatted using Prettier. Please run bun format before committing to ensure your code matches the project's style.
  • Linting: Code quality and potential errors are checked using ESLint based on the configuration in eslint.config.js. Run bun lint to check your code and bun lint:fix to automatically fix issues.
  • Naming Conventions:
    • Use camelCase for variables, functions, and method names.
      • Strive for descriptive names that clearly indicate the variable's purpose (e.g., staticPathCache, currentNode, pluginMatch rather than generic names like cache, node, or flag).
    • Use PascalCase for classes, types, and interfaces (e.g., Extreme, PluginHandler, Node).
    • Use UPPER_SNAKE_CASE for constants and enum members (e.g., ErrorTypes.PluginMissingId, UUID_REGEX).
  • TypeScript:
    • This project uses TypeScript with strict mode enabled (tsconfig.json). Ensure your contributions are strongly typed.
    • Leverage TypeScript features like interfaces, types, and enums as used throughout the project (see src/types.ts).
  • Modules: Use ES Modules (import/export) syntax.
  • Comments: Use JSDoc/TSDoc style comments for explaining functions, classes, and complex logic. Use // for brief inline comments.
  • Error Handling: Follow the existing pattern of using the ErrorTypes enum (src/types.ts) and the throwError method where applicable.

Pre-commit Hook: Remember that Husky runs bun lint-staged (which includes formatting and linting) and bun run test:coverage --changed automatically before each commit (.husky/pre-commit). Ensure these checks pass.

Testing

Extreme Router uses Vitest for testing. Please ensure that your contribution includes relevant tests and that the entire test suite passes.

  • Run the full test suite: 
    bun run test
  • Run tests in watch mode: 
    bun run test:watch
  • Generate a coverage report (output in ./coverage/): 
    bun run test:coverage

As mentioned, the pre-commit hook also runs bun run test:coverage --changed to ensure tests related to your changes pass and maintain coverage.

Test Utilities (tests/test-util.ts)

To facilitate more thorough testing, especially for internal logic and state, the project includes a test utility class TestExtreme located in tests/test-util.ts. This class extends the main Extreme router and exposes several internal properties and methods (e.g., getStaticPathCache(), getRoot(), getPlugins(), throwError()).

When writing tests that need to inspect or interact with the router's internals, you can import and use TestExtreme instead of the standard Extreme class. This allows for more direct assertions on the router's state and behavior.

Checking Bundle Size

Ensure the bundle size remains reasonable after your changes:

bun run size

This command checks the size of the built files and saves a report to dist/bundle-size.json. Review this report to ensure your changes haven't significantly increased the bundle size unexpectedly.

Benchmarking

Extreme Router includes performance and memory benchmarks to help contributors ensure that changes do not negatively impact speed or memory usage.

  • General matching benchmark (mixed and 25 routes by default): 
    bun benchmark
  • Run specific benchmarks (25 routes by default): 
    bun benchmark:dynamic
bun benchmark:static
bun benchmark:stress
bun benchmark:memory
  • (Optional) Specify number of routes: 
    bun benchmark --routes=<number>
bun benchmark:dynamic --routes=<number>
# ... and so on for other specific benchmarks

Benchmark results are logged to the console. Please run relevant benchmarks if your changes may affect performance or memory usage.

Running All Benchmarks

A script is available to run all benchmark combinations (runtimes, types, route counts) and save their outputs to the benchmark/results/ directory:

bun run scripts/run-all-benchmarks.js

You can also specify a runtime (e.g., bun or node):

bun run scripts/run-all-benchmarks.js --type bun
bun run scripts/run-all-benchmarks.js --type node

This is useful for comprehensive performance regression testing.

License

By contributing to Extreme Router, you agree that your contributions will be licensed under its MIT License.