Skip to content

Latest commit

 

History

History
305 lines (214 loc) · 8.17 KB

CONTRIBUTING.md

File metadata and controls

305 lines (214 loc) · 8.17 KB

Contributing to NoobHeaders

First off, thank you for considering contributing to NoobHeaders! 🎉

Table of Contents

Code of Conduct

This project and everyone participating in it is governed by a simple rule: Be respectful and constructive.

How Can I Contribute?

Reporting Bugs

Before creating bug reports, please check the existing issues to avoid duplicates. When you create a bug report, include as many details as possible:

  • Use a clear and descriptive title
  • Describe the exact steps to reproduce the problem
  • Provide specific examples
  • Describe the behavior you observed and what you expected
  • Include screenshots if relevant
  • Specify your browser and OS

Suggesting Enhancements

Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion:

  • Use a clear and descriptive title
  • Provide a detailed description of the suggested enhancement
  • Explain why this enhancement would be useful
  • List any alternatives you've considered

Pull Requests

We actively welcome your pull requests:

  1. Fork the repo and create your branch from main
  2. Make your changes
  3. If you've added code, add tests
  4. Ensure the test suite passes
  5. Make sure your code lints
  6. Issue the pull request

Development Setup

Prerequisites

  • Node.js 22+
  • pnpm 10+ (the version is pinned by packageManager in package.json)

Setup Steps

  1. Clone your fork:

    git clone https://github.com/YOUR_USERNAME/noobheaders.git
    cd noobheaders
  2. Install dependencies:

    pnpm install
  3. Generate icons:

    pnpm run icons
  4. Load extension in browser:

    • Chrome: chrome://extensions/ → Enable Developer mode → Load unpacked
    • Firefox: about:debugging → Load Temporary Add-on

Development Workflow

# Run tests
pnpm test

# Run E2E tests (run `pnpm exec playwright install chromium` once; Firefox needs FIREFOX_BIN)
pnpm test:e2e

# Run Firefox manual validation
pnpm test:firefox

# Lint code
pnpm run lint

# Type check
pnpm run typecheck

# Format code
pnpm run format

# Run all checks
pnpm run check

Pull Request Process

  1. Update documentation if needed
  2. Add tests for new features
  3. Ensure all tests pass: pnpm test
  4. Ensure code is formatted: pnpm run format
  5. Ensure code is linted and type checks: pnpm run lint and pnpm run typecheck
  6. Update CHANGELOG.md if it's a significant change
  7. Use conventional commits (see below)

PR Checklist

  • Code follows the project's coding style
  • Tests added/updated and passing
  • Documentation updated
  • CHANGELOG.md updated (if needed)
  • Commits follow conventional commit format
  • PR description clearly describes the changes

Coding Guidelines

JavaScript Style

  • Use modern ES6+ syntax
  • Use async/await for asynchronous code
  • Use const and let, not var
  • Use template literals for strings
  • Add JSDoc comments for functions
  • Keep functions small and focused
  • Use meaningful variable names

Example:

/**
 * Convert profile to declarativeNetRequest rules
 * @param {Object} profile - Profile object
 * @param {number} ruleIdOffset - Starting rule ID
 * @returns {Array} Array of rules
 */
function convertProfileToRules(profile, ruleIdOffset = 1) {
  const rules = [];
  // Implementation...
  return rules;
}

HTML/CSS Style

  • Use semantic HTML
  • Keep styles modular and reusable
  • Use CSS custom properties for theming
  • Follow BEM naming for complex components
  • Ensure accessibility (ARIA labels, keyboard navigation)

Commit Messages

We use Conventional Commits for automated versioning and changelog generation.

Format

<type>(<scope>): <subject>

<body>

<footer>

Types

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

Examples

feat(profiles): add profile duplication feature

Add ability to duplicate existing profiles with a single click.
Users can now quickly create variations of existing configurations.

Closes #123

fix(filters): correct domain filter matching

Domain filters were not matching subdomains correctly.
Updated regex to properly handle subdomain matching.

feat(ui): add dark mode support

BREAKING CHANGE: Theme CSS custom properties have been renamed

Scope

Common scopes:

  • profiles - Profile management
  • headers - Header modification
  • filters - Filter system
  • ui - User interface
  • i18n - Internationalization
  • ci - CI/CD
  • docs - Documentation

Commit message format (enforced)

We enforce a Conventional Commit format with this additional rule:

  • The commit must follow: <type>(<scope>)?: <gitmoji> <short description>
    • Example: chore(ci): 📦 publish release assets
    • A Husky commit-msg hook runs scripts/verify-commit-msg.js locally to validate this format.
    • The check requires an emoji immediately after the colon (e.g., : 📦) and a short description following it.

If a commit fails the check the hook will block the commit and show the expected format.

Testing

Running Tests

# Run all tests
pnpm test

# Run specific test file
node --test tests/manifest.test.js

Release Process

Releases are handled automatically with semantic-release. As part of the release pipeline, we run node scripts/update-version.js ${nextRelease.version} which updates manifest*.json (e.g., manifest.json, manifest.chrome.json, manifest.firefox.json) and replaces any vX.Y.Z occurrences in top-level HTML files (for example options.html, popup.html, welcome.html) so the version displayed in the UI matches the release version. The updated files are then committed by semantic-release and included in the release artifacts.

If you need to perform a local dry-run, run:

node scripts/update-version.js 1.2.3

Remember to revert those changes after testing (or commit them as part of your release branch).

Pre-commit and pre-push hooks

To keep the repository clean and avoid manual lint/fix cycles, we run auto-fixes and formatting automatically when committing and run the test-suite before pushing:

  • pre-commit: runs Biome (lint + format) on the staged files through lint-staged
  • pre-push: runs pnpm test and blocks the push if tests fail

These hooks are set up using husky and lint-staged. They are enabled automatically by pnpm install (through the prepare script).

Automated Dependabot merges

Dependabot PRs for patch and minor updates get GitHub auto-merge enabled (.github/workflows/dependabot-automerge.yml). They are merged only once the required CI checks (lint, unit tests, Chromium and Firefox E2E, packaging) pass on the PR. Major updates are left for a manual review.

This requires "Allow auto-merge" in the repository settings and a branch protection rule on main that requires the CI checks. To opt out for a specific dependency, add an ignore rule to .github/dependabot.yml.

Writing Tests

  • Place tests in tests/ directory
  • Name test files with .test.js suffix
  • Use Node.js built-in test runner
  • Aim for >80% code coverage

Example test:

import { test } from 'node:test';
import assert from 'node:assert';

test('generateId creates unique IDs', () => {
  const id1 = generateId();
  const id2 = generateId();
  assert.notEqual(id1, id2);
});

Documentation

  • Update README.md for user-facing changes
  • Update code comments for implementation changes
  • Add JSDoc comments for new functions
  • Update examples/ for new features

Questions?

Feel free to open an issue with the question label!


Thank you for contributing to NoobHeaders! 🎓💜