Skip to content

Contributing

Jump to bottom
Gautam Krishna R edited this page Dec 1, 2025 · 1 revision

Contributing to OTP Manager

Thank you for your interest in contributing to OTP Manager! This guide will help you get started.

Code of Conduct

By participating in this project, you agree to:

  • Be respectful and inclusive
  • Welcome newcomers
  • Focus on what's best for the community
  • Show empathy towards others
  • Accept constructive criticism gracefully

How Can I Contribute?

Reporting Bugs

Before creating a bug report:

  1. Check existing issues to see if the bug was already reported
  2. Use the latest version to confirm the bug still exists
  3. Gather information about the bug:
    • Steps to reproduce
    • Expected behavior
    • Actual behavior
    • Screenshots (if applicable)
    • Environment details (OS, browser, Node version)

Create a bug report: New Bug Report

Use this template:

**Describe the bug**
A clear and concise description of what the bug is.

**To Reproduce**
Steps to reproduce the behavior:
1. Go to '...'
2. Click on '...'
3. See error

**Expected behavior**
What you expected to happen.

**Screenshots**
If applicable, add screenshots.

**Environment:**
- OS: [e.g., macOS, Windows, Linux]
- Browser: [e.g., Chrome, Firefox, Safari]
- Version: [e.g., 1.0.0]

**Additional context**
Any other context about the problem.

Suggesting Features

Before creating a feature request:

  1. Check existing feature requests to avoid duplicates
  2. Verify it aligns with the project goals
  3. Provide a clear use case for the feature

Request a feature: New Feature Request

Use this template:

**Is your feature request related to a problem?**
A clear description of the problem.

**Describe the solution you'd like**
A clear description of what you want to happen.

**Describe alternatives you've considered**
Other solutions or features you've considered.

**Additional context**
Any other context, screenshots, or examples.

Contributing Code

First-Time Contributors

Great first issues:

  • Documentation improvements
  • Adding tests
  • Fixing typos
  • Code comments
  • UI/UX improvements

Look for issues labeled good first issue or help wanted.

Development Process

  1. Fork and Clone

    git clone https://github.com/YOUR-USERNAME/otpshare.git
cd otpshare

  2. Set Up Development Environment

  3. Create a Feature Branch

    git checkout -b feature/your-feature-name

    Branch naming conventions:

    • feature/ for new features
    • fix/ for bug fixes
    • docs/ for documentation
    • refactor/ for code refactoring
    • test/ for adding tests

  4. Make Your Changes

    • Write clean, readable code
    • Follow existing code style
    • Add/update tests as needed
    • Update documentation if needed

  5. Test Your Changes

    # Run all checks
yarn check

# Individual checks
yarn lint          # Linting
yarn format        # Code formatting
yarn build         # Type checking
yarn test          # Run tests

  6. Commit Your Changes

    git add .
git commit -m "feat: add amazing feature"

    Follow Conventional Commits:

    • feat: new feature
    • fix: bug fix
    • docs: documentation changes
    • style: formatting, missing semicolons, etc.
    • refactor: code refactoring
    • test: adding tests
    • chore: maintenance tasks

  7. Push to Your Fork

    git push origin feature/your-feature-name

  8. Open a Pull Request

    • Go to the original repository
    • Click "New Pull Request"
    • Select your branch
    • Fill in the PR template
    • Submit!

Pull Request Guidelines

PR Checklist

Before submitting your PR, ensure:

  • Code follows the project's code style (enforced by Biome)
  • All tests pass (yarn test)
  • Linting passes (yarn lint)
  • TypeScript compiles without errors (yarn build)
  • Documentation is updated (if needed)
  • Commit messages follow conventional commits
  • Branch is up to date with master

PR Template

## Description
Brief description of changes.

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## How Has This Been Tested?
Describe the tests you ran.

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review of code completed
- [ ] Commented code (particularly hard-to-understand areas)
- [ ] Documentation updated
- [ ] No new warnings generated
- [ ] Tests added/updated
- [ ] All tests passing

Review Process

  1. Automated Checks

    • GitHub Actions run tests and linting
    • All checks must pass

  2. Code Review

    • Maintainers will review your code
    • Address any requested changes
    • Discussion may happen in PR comments

  3. Approval and Merge

    • Once approved, maintainers will merge
    • Your contribution will be in the next release!

Documentation Guidelines

Code Comments

// Good: Explain WHY, not WHAT
// Use optimistic locking to prevent race conditions
const lockVersion = await getVersion();

// Avoid: Obvious comments
// Get the user
const user = getUser();

JSDoc for Public APIs

/**
 * Imports OTP codes from a vendor file
 * @param file - The uploaded file buffer
 * @param vendor - Vendor identifier (e.g., 'tp-link-omada')
 * @returns Array of extracted OTP codes
 * @throws {Error} If file format is invalid
 */
export const importFromVendor = async (
  file: Buffer,
  vendor: string
): Promise<string[]> => {
  // Implementation
};

Documentation Files

When updating features:

  1. Update relevant wiki pages
  2. Update README if necessary
  3. Add examples for new features
  4. Include screenshots for UI changes

Adding Vendor Integrations

See the detailed guide: Adding Vendor Integrations

Quick overview:

  1. Create parser in packages/backend/src/parsers/
  2. Implement the VendorParser interface
  3. Register parser in parsers/index.ts
  4. Add vendor option to frontend import modal
  5. Write tests for the parser
  6. Document the integration in wiki

Community

Getting Help

Staying Updated

  • Watch the repository for notifications
  • Follow releases for new versions
  • Check the changelog

License

By contributing, you agree that your contributions will be licensed under the GNU Affero General Public License v3.0.

Clone this wiki locally