Skip to main content
Thank you for considering contributing to Open Mushaf Native! This guide will help you understand our development workflow and standards.

​
Getting Started

​
Reporting Issues

Before creating a new issue:
  1. Search existing issues to avoid duplicates
  2. Use the issue templates when available
  3. Provide detailed information:
    • Steps to reproduce
    • Expected vs actual behavior
    • Screenshots or videos if applicable
    • Device/platform information
    • App version
Open issues on the GitHub Issues page

​
Pull Request Workflow

1

Fork and clone

Fork the repository and clone your fork:
git clone https://github.com/your-username/open-mushaf-native.git
cd open-mushaf-native
2

Create a feature branch

Use a descriptive branch name:
git checkout -b feature/your-feature-name
Branch naming conventions:
  • feature/ - New features
  • fix/ - Bug fixes
  • docs/ - Documentation updates
  • refactor/ - Code refactoring
  • test/ - Test additions or updates
3

Make your changes

  • Follow the code style guidelines (enforced by ESLint)
  • Write meaningful commit messages
  • Add tests if applicable
  • Update documentation as needed
4

Test your changes

Ensure all linting passes:
npm run lint
Pull requests must have zero ESLint errors to be accepted
5

Commit your changes

We use conventional commits (enforced by commitlint):
git add .
npm run commit
Or manually:
git commit -m "feat: add new feature"
6

Push to your fork

git push origin feature/your-feature-name
7

Create a pull request

  • Go to the original repository
  • Click “New Pull Request”
  • Select your fork and branch
  • Fill out the PR template
  • Link related issues

​
Code Style Guidelines

​
ESLint Configuration

The project uses ESLint with the following plugins:
  • expo - Expo-specific rules
  • prettier - Code formatting
  • import - Import/export sorting
  • react-compiler - React Compiler rules

​
Import Order

Imports are automatically sorted by the import/order rule: 
// 1. React and React Native (external)
import React from 'react';
import { View, Text } from 'react-native';

// 2. Other external packages
import { useAtom } from 'jotai';
import { useRouter } from 'expo-router';

// 3. Internal packages (@src/**)
import { theme } from '@src/constants/theme';

// 4. Sibling/parent imports
import { Button } from '../components/Button';
import { utils } from './utils';
Imports are automatically sorted alphabetically and case-insensitively

​
Code Formatting

The project uses Prettier for consistent code formatting. Formatting is automatically applied:
  • On save (if your editor is configured)
  • Before each commit (via lint-staged)
  • When running npm run lint:fix

​
Commit Conventions

​
Commit Message Format

We follow Conventional Commits specification: 
<type>(<scope>): <subject>

<body>

<footer>

​
Commit Types

TypeDescriptionExample
featNew feature or functionalityfeat: add audio playback controls
fixBug fix or correctionfix: resolve page navigation crash
docsDocumentation changesdocs: update setup instructions
styleCode style changes (formatting)style: apply prettier formatting
refactorCode refactoringrefactor: simplify state management
perfPerformance improvementsperf: optimize image loading
testAdding or updating teststest: add unit tests for utils
choreRoutine tasks, dependencieschore: update dependencies
revertReverting a previous commitrevert: undo feature X
ciCI configuration changesci: update GitHub Actions
wipWork in progresswip: implement new feature

​
Using Commitizen

The project includes Commitizen for interactive commit messages: 
npm run commit
This will guide you through creating a properly formatted commit message.

​
Commit Rules

  • Header max length: 200 characters
  • Type: Must be lowercase (feat, fix, etc.)
  • Scope: Optional, any case allowed
  • Subject: Any case allowed
  • Body: No line length limit for detailed descriptions
Commits that don’t follow the conventional format will be rejected by the commit-msg hook

​
Git Hooks

The project uses Husky to enforce quality standards:

​
pre-commit

Runs automatically before each commit:
  1. Prettier - Formats code
  2. ESLint - Fixes linting issues
Affected files: **/*.{js,jsx,ts,tsx}

​
commit-msg

Validates commit messages using commitlint to ensure they follow conventional commit format.

​
Best Practices

​
Code Quality

  • Write self-documenting code with clear variable and function names
  • Add comments for complex logic
  • Keep functions small and focused on a single responsibility
  • Avoid deeply nested conditionals
  • Use TypeScript types properly, avoid any

​
State Management

The project uses Jotai for state management:
  • Create atoms for shared state
  • Use jotai-effect for side effects
  • Keep atoms focused and composable

​
Performance

  • Use React.memo for expensive components
  • Optimize re-renders with proper dependency arrays
  • Use expo-image for efficient image handling
  • Test on low-end devices

​
Accessibility

  • Add proper accessibility labels
  • Test with screen readers
  • Ensure sufficient color contrast
  • Support text scaling

​
Questions and Support

If you have questions:
  1. Check existing documentation
  2. Search closed issues and discussions
  3. Open a new issue with the “question” label
  4. Reach out through the GitHub repository
Thank you for contributing to Open Mushaf Native!

Build docs developers (and LLMs) love

Get started for freeTalk to us