Contributing

OpenScouter welcomes contributions from developers, accessibility experts, and community members. This guide explains how to contribute effectively.

Getting Started

Before writing any code, check the issue tracker in the repository to see whether the change you have in mind is already being discussed. For significant changes, open an issue first to align on the approach before investing time in implementation.

For small fixes (typos, documentation, minor bugs), you can open a pull request directly.

Forking and Branching

1. Fork the repository

Click Fork on the GitHub repository page. This creates a copy under your own account.

2. Clone your fork

git clone https://github.com/<your-username>/openscouter.git
cd openscouter
git remote add upstream https://github.com/your-org/openscouter.git

3. Create a branch

Branch names follow this convention:

Type	Pattern	Example
New feature	feature/<short-description>	feature/telegram-notifications
Bug fix	fix/<short-description>	fix/token-expiry-check
Documentation	docs/<short-description>	docs/deployment-guide
Refactor	refactor/<short-description>	refactor/extract-auth-helpers

git checkout -b feature/your-feature-name

Keep branches focused. One branch, one purpose.

Making Changes

Follow the Code Style guide. The key points:

• Use TypeScript strict mode. No any.
• Use function components. No class components.
• Use kebab-case for file names and PascalCase for component names.
• Keep functions under 50 lines.
• Handle errors explicitly at every level.

Writing Tests

Tests are required. Pull requests that reduce coverage below 80% will not be merged.

Follow the Testing guide. In practice this means:

1. Write tests before or alongside your implementation.
2. Cover the happy path, error cases, and edge cases.
3. Place unit tests next to the file they test.
4. Run the full test suite locally before pushing.

npm run test
npm run test:e2e

Before Opening a Pull Request

Run these checks locally and fix any failures:

npm run typecheck   # TypeScript
npm run lint        # ESLint
npm run format      # Prettier
npm run build       # production build
npm run test        # unit + integration tests

Review your own diff before requesting a review. Look for debug logs left in, commented-out code, hardcoded values, or anything you would flag in someone else’s pull request.

Pull Request Description

A good pull request description includes:

• What the change does and why it is needed.
• A link to the related issue if one exists.
• A test plan describing what you tested and how a reviewer can verify the change.
• Any known limitations or follow-up work.

Keep the pull request small. A focused PR with a clear description is reviewed faster and merged more reliably than a large one.

Review Process

At least one maintainer approval is required before merge. Reviewers may request changes. Address feedback by pushing additional commits to the same branch. Do not force-push after a review has started unless asked to.

Once approved, a maintainer will merge the pull request. Merges use the squash strategy to keep the commit history on main clean.

Reporting Issues

If you find a bug or want to suggest a feature, open an issue on GitHub. Include:

• A clear title.
• Steps to reproduce the issue (for bugs).
• What you expected to happen and what actually happened.
• The environment (OS, browser, Node version) if relevant.

For security vulnerabilities, do not open a public issue. See the Vulnerability Disclosure policy instead.