Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
135 lines (93 loc) · 3.78 KB

CONTRIBUTING.md

File metadata and controls

135 lines (93 loc) · 3.78 KB
Raw

UAParser.js: How to Contribute

Thank you for your interest in contributing to UAParser.js! This document covers everything you need to get started, from setting up your environment to submitting a pull request.

Table of Contents

Getting Started

  1. Fork this repository and clone your fork: 
    git clone https://github.com/<your-username>/ua-parser-js.git
cd ua-parser-js
  2. Install dependencies: 
    npm install
  3. Verify everything works before making changes: 
    npm run build+test

Development Workflow

  • Source files are under /src directory.
  • Test files are under /test directory.
  • After editing source files, rebuild the distribution bundles: 
    npm run build

Adding New Detection Rules

When adding a new detection rule, make sure to also update the enums in /src/enums/ua-parser-enum.js.

Adding or Updating Regex Patterns

  • Add patterns to the relevant section inside /src/main/ua-parser.js or /src/extensions/ua-parser-extensions.js.
  • Every new pattern must have a corresponding unit test.
  • Run safe-regex checks to confirm no new pattern introduces catastrophic backtracking by running: 
    npm run test
  • Keep in mind that UA strings are capped at 500 characters at parse time.

Testing

All pull requests must pass the full test suite. Please add or update tests under /test when changing parser behaviour.

Security Guidelines

We take security seriously. Please follow these rules when contributing:

  • No eval(), new Function(), or other unsafe pattern.
  • Validate and sanitize inputs: User-Agent strings are untrusted data.
  • Regex safety: verify patterns with safe-regex before adding new regular expressions.
  • Do not introduce new production dependencies without prior discussion in an issue. The current production dependency footprint is intentionally minimal.

To report a security vulnerability, please follow the process described in SECURITY.md.

Dependency

Adding Dependencies

  • Production dependencies (dependencies in package.json): requires explicit maintainer approval. Open an issue before adding one.
  • Dev dependencies (devDependencies): allowed for tooling, but well-maintained packages are preferred.
  • All dependencies must use OSI-approved permissive licenses.

Commit Message Convention

This project adopts the Conventional Commits specification. All commit messages should be structured as:

<type>(<scope>): <short summary>

[optional body]

[optional footer(s)]

Breaking Changes

Append ! after the type/scope and add a BREAKING CHANGE: footer:

feat!: rename getUA() to getUserAgent()

BREAKING CHANGE: getUA() has been renamed to getUserAgent() for clarity.

Commits with BREAKING CHANGE trigger a minor/major version bump in releases.

Submitting a Pull Request

  1. Create a feature branch from master: 
    git checkout -b fix/my-improvement
  2. Make your changes, with tests.
  3. Run the full suite: 
    npm run build+test
  4. Push and open a Pull Request against master.
  5. Don't forget to check the CLA acknowledgement in the PR submission form.
  6. A maintainer will review your PR. Please be responsive to feedback.

Code of Conduct

This project follows the UAParser.js Code of Conduct. By participating, you agree to uphold it.