First off, thank you for considering contributing to NoobHeaders! 🎉
- Code of Conduct
- How Can I Contribute?
- Development Setup
- Pull Request Process
- Coding Guidelines
- Commit Messages
This project and everyone participating in it is governed by a simple rule: Be respectful and constructive.
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
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
We actively welcome your pull requests:
- Fork the repo and create your branch from
main - Make your changes
- If you've added code, add tests
- Ensure the test suite passes
- Make sure your code lints
- Issue the pull request
- Node.js 22+
- pnpm 10+ (the version is pinned by
packageManagerinpackage.json)
-
Clone your fork:
git clone https://github.com/YOUR_USERNAME/noobheaders.git cd noobheaders -
Install dependencies:
pnpm install
-
Generate icons:
pnpm run icons
-
Load extension in browser:
- Chrome:
chrome://extensions/→ Enable Developer mode → Load unpacked - Firefox:
about:debugging→ Load Temporary Add-on
- Chrome:
# 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- Update documentation if needed
- Add tests for new features
- Ensure all tests pass:
pnpm test - Ensure code is formatted:
pnpm run format - Ensure code is linted and type checks:
pnpm run lintandpnpm run typecheck - Update CHANGELOG.md if it's a significant change
- Use conventional commits (see below)
- 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
- 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
/**
* 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;
}- 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)
We use Conventional Commits for automated versioning and changelog generation.
<type>(<scope>): <subject>
<body>
<footer>
- 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
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 renamedCommon scopes:
profiles- Profile managementheaders- Header modificationfilters- Filter systemui- User interfacei18n- Internationalizationci- CI/CDdocs- Documentation
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-msghook runsscripts/verify-commit-msg.jslocally to validate this format. - The check requires an emoji immediately after the colon (e.g.,
: 📦) and a short description following it.
- Example:
If a commit fails the check the hook will block the commit and show the expected format.
# Run all tests
pnpm test
# Run specific test file
node --test tests/manifest.test.jsReleases 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.3Remember to revert those changes after testing (or commit them as part of your release branch).
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 throughlint-stagedpre-push: runspnpm testand 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).
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.
- Place tests in
tests/directory - Name test files with
.test.jssuffix - 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);
});- Update README.md for user-facing changes
- Update code comments for implementation changes
- Add JSDoc comments for new functions
- Update examples/ for new features
Feel free to open an issue with the question label!
Thank you for contributing to NoobHeaders! 🎓💜