Skip to main content

​
Welcome Contributors!

Thank you for considering contributing to Open Tarteel! We appreciate your help in making this project better. This guide will walk you through the contribution process.

​
Ways to Contribute

There are many ways to contribute to Open Tarteel:
  • Report bugs and issues
  • Suggest new features or enhancements
  • Improve documentation
  • Submit bug fixes
  • Add new features
  • Improve code quality and performance
  • Help with translations (i18n)

​
Getting Started

1

Set Up Your Development Environment

Follow the development setup guide to configure your local environment.
2

Find an Issue or Create One

  • Browse the GitHub Issues page
  • Look for issues labeled good first issue or help wanted
  • If you have a new idea, create an issue first to discuss it
3

Fork and Clone

Fork the repository and clone it to your local machine:
git clone https://github.com/your-username/open-tarteel.git
cd open-tarteel

​
Development Workflow

​
1. Create a Feature Branch

Always create a new branch for your work. Use a descriptive name that reflects your changes: 
git checkout -b feature/add-bookmark-functionality
Branch naming convention: type/description-in-kebab-caseCommon types: feature, fix, docs, refactor, test, chore

​
2. Make Your Changes

Implement your feature or fix following these guidelines:

​
Code Style

  • Follow the existing code style and conventions
  • Use TypeScript for all new code
  • Use functional components with hooks
  • Leverage Tailwind CSS for styling
  • Use Jotai for state management
import { useAtom } from 'jotai';
import { playerStateAtom } from '@/jotai/atoms';

export const MyComponent = () => {
  const [playerState, setPlayerState] = useAtom(playerStateAtom);
  
  return (
    <div className="flex items-center justify-center">
      {/* Component content */}
    </div>
  );
};

​
Path Aliases

Use configured path aliases for imports: 
// ✅ Good
import { Button } from '@/components/button';
import { usePlayer } from '@/hooks/usePlayer';
import type { Reciter } from '@/types/reciter';

// ❌ Avoid
import { Button } from '../../../components/button';

​
3. Test Your Changes

Before committing, ensure your changes work correctly:
1

Run Development Server

npm run dev
Test your changes in the browser at http://localhost:3000
2

Check Types

npm run type-check
Ensure there are no TypeScript errors.
3

Run Linter

npm run lint:fix
Fix any linting issues automatically.
4

Test Production Build

npm run build
npm start
Verify your changes work in production mode.

​
4. Commit Your Changes

The project uses Conventional Commits with Commitizen support: 
git add .
git commit -m "feat(player): add shuffle functionality"

​
Commit Message Format

type(scope): subject

[optional body]

[optional footer]
Commit Types:
  • feat - New feature
  • fix - Bug fix
  • docs - Documentation changes
  • style - Code style changes (formatting, etc.)
  • refactor - Code refactoring
  • perf - Performance improvements
  • test - Adding or updating tests
  • chore - Maintenance tasks
  • ci - CI/CD changes
  • build - Build system changes
Examples: 
feat(player): add repeat one functionality
fix(ui): resolve mobile navigation overflow
docs(readme): update installation instructions
refactor(hooks): simplify useAudioPlayer logic
Commits that don’t follow the conventional format will be rejected by the commit hook.

​
5. Push Your Changes

Push your branch to your fork: 
git push origin feature/your-feature-name

​
6. Create a Pull Request

1

Open Pull Request

Go to the Open Tarteel repository and click “New Pull Request”.
2

Write Clear Description

Provide a clear description of your changes:
  • What does this PR do?
  • Why are these changes needed?
  • How did you test these changes?
  • Screenshots (if UI changes)
  • Related issues (use Closes #123 or Fixes #123)
3

Wait for Review

A maintainer will review your PR. Be responsive to feedback and make requested changes if needed.

​
Pull Request Checklist

Before submitting your PR, ensure:
  • Code follows project style guidelines
  • All tests pass (npm run build)
  • Type checking passes (npm run type-check)
  • Linting passes (npm run lint)
  • Commit messages follow conventional format
  • Documentation is updated (if needed)
  • Changes are tested in both development and production modes

​
Reporting Issues

When reporting bugs or issues, please include:
  1. Clear Description - What is the problem?
  2. Steps to Reproduce - How can we reproduce the issue?
  3. Expected Behavior - What should happen?
  4. Actual Behavior - What actually happens?
  5. Environment - Browser, OS, device
  6. Screenshots - If applicable
  7. Console Errors - Any error messages
Use the GitHub Issues page to report bugs or request features.

​
Feature Requests

When suggesting new features:
  1. Check Existing Issues - Has someone already requested this?
  2. Describe the Feature - What functionality do you want?
  3. Use Cases - Why is this feature valuable?
  4. Alternatives - Have you considered other approaches?
  5. Additional Context - Mockups, examples, or references

​
Code Review Process

All contributions go through code review:
  1. Automated Checks - Linting, type checking, build
  2. Manual Review - A maintainer reviews your code
  3. Feedback - Address any requested changes
  4. Approval - Once approved, your PR will be merged
Reviews typically happen within 2-3 business days. Be patient and responsive to feedback.

​
Community Guidelines

  • Be respectful and inclusive
  • Provide constructive feedback
  • Help other contributors
  • Follow the code of conduct
  • Ask questions when unsure

​
Questions?

If you have any questions:

​
Recognition

All contributors are recognized in the project. Your contributions, no matter how small, are valued and appreciated! Thank you for contributing to Open Tarteel! 🎉

Build docs developers (and LLMs) love

Get started for freeTalk to us