Skip to main content

​
Welcome Contributors!

Contributions are always welcome! This guide will help you understand the contribution process and best practices for the Skiff project.

​
Code of Conduct

Skiff contributors adhere to the Contributor Covenant as our Code of Conduct. Please read and follow the full text available in CODE_OF_CONDUCT.md.

​
Getting Started

​
Finding an Issue

1

Browse Good First Issues

Start with issues labeled good first issue. These are:
  • Small in scope
  • Have clear solutions in the description
  • Perfect for first-time contributors
2

Explore Dev Ready Issues

Once familiar with the codebase, look at dev ready issues:
  • Slightly larger in scope
  • Well-defined solutions
  • Ready for implementation
3

Claim an Issue

Before starting work, comment on the issue thread to claim it:
I'd like to work on this issue.
You’ll be assigned to the issue and appear in the “Assignee” section.
Important: Always claim an issue before starting work to avoid duplicated effort. If there’s no progress for 7 days, anyone can take over the issue.

​
Issues Without Clear Solutions

Issues that lack a clear solution or aren’t on the roadmap will undergo a longer development and review process. Consider discussing your approach in the issue comments before starting.

​
Opening a Pull Request

​
Before You Start

Always create an issue first before opening a Pull Request. Keep PRs small and associated with only a single issue for faster review.

​
Step-by-Step Process

1

Fork the Repository

Fork the repository to your GitHub account:Fork skiff-apps
2

Clone and Setup

Clone your fork and add the upstream remote:
git clone https://github.com/<your-username>/skiff-apps.git
cd skiff-apps
git remote add upstream https://github.com/skiff-org/skiff-apps.git
3

Sync with Main

Synchronize your local main branch:
git checkout main
git pull upstream main
4

Install Dependencies

Install dependencies with Yarn:
yarn install
5

Create Feature Branch

Create a new branch with the issue number:
git checkout -b feature/issue-123-short-description
Include the issue number in your branch name for easy tracking.
6

Make Your Changes

Implement your changes, following the code style guidelines below.
7

Run Quality Checks

Before committing, ensure your code passes all checks:
# Format code with Prettier
yarn prettier

# Lint code
yarn lint

# Check TypeScript types
yarn typescript
These checks will be run by CI. Fix any issues before opening your PR.
8

Commit and Push

Commit your changes and push to your fork:
git add .
git commit -m "[#123] Add feature description"
git push -u origin HEAD
9

Open Pull Request

Go to the repository and create a Pull Request from your branch.

​
Pull Request Structure

​
Branch Guidelines

  • All branches should target main
  • Include the reference issue number in the branch name
  • Use descriptive names: feature/issue-123-add-dark-mode

​
PR Title Format

Use this format for PR titles: 
[Issue #] [Component] Imperative description
Examples:
  • [#1045] [Button] Add force theme support
  • [#892] [ComposePanel] Fix attachment upload error
  • [#1234] [Auth] Implement two-factor authentication

​
PR Description

Your PR description should include:
  1. Summary: Brief overview of the changes
  2. How to Review: Guide reviewers on code structure
  3. Testing: How you tested the changes
  4. Screenshots: For UI changes
  5. Related Issues: Link to the issue being addressed
Template: 
## Summary
Implements dark mode support for the Button component.

## How to Review
- Check `components/Button/Button.tsx` for theme logic
- Review `hooks/useTheme.ts` for new theme utilities

## Testing
- Tested manually in both light and dark modes
- Added unit tests in `Button.test.tsx`

## Screenshots
[Include before/after screenshots]

## Related Issues
Closes #1045

​
Quality Requirements

  • All code must be linted: yarn lint
  • All code must be formatted: yarn prettier
  • All code must be type-safe: yarn typescript
  • Self-review and comment on your own code

​
Code Style

​
Automated Formatting

The project uses Prettier for code formatting and ESLint for code quality. 
yarn prettier

​
Editor Setup

Enable lint-on-save in your editor for the best development experience.
VS Code settings (.vscode/settings.json): 
{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  }
}

​
Style Guidelines

  • Use TypeScript for all new code
  • Follow functional programming patterns where possible
  • Prefer React hooks over class components
  • Use meaningful variable names
  • Add comments for complex logic
  • Keep functions small and focused

​
Review Process

Once you open a PR:
  1. Automated Checks: CI will run linting, type checking, and tests
  2. Code Review: Core team members will review your code
  3. Feedback: Address any requested changes
  4. Approval: Once approved, your PR will be merged
The core team will promptly review your Pull Request and either merge it or request changes.

​
Communication

​
Where to Ask Questions

  • Issue Comments: For questions about specific issues
  • PR Comments: For questions about your implementation
  • GitHub Discussions: For general questions about the project

​
Response Times

  • Issue Claims: Immediate (comment to claim)
  • PR Reviews: Usually within 3-5 business days
  • Questions: Best-effort response within 1-2 business days

​
Common Scenarios

Sync your branch with the latest main:
git checkout main
git pull upstream main
git checkout your-branch
git rebase main
git push --force-with-lease
Run the checks locally:
yarn prettier
yarn lint
yarn typescript
yarn test
Fix any issues and push again.
Simply push more commits to your branch:
git add .
git commit -m "Address review feedback"
git push
The PR will update automatically.
Yes! Create separate branches for each issue:
git checkout main
git pull upstream main
git checkout -b feature/issue-456-another-feature

​
Recognition

Contributors are recognized in:
  • GitHub’s contributor graph
  • Release notes (for significant contributions)
  • The community (through issue/PR interactions)

​
License

By contributing to Skiff, you agree that your contributions will be licensed under the same license as the project. See LICENSE for details.

​
Additional Resources

Development Setup

Set up your local environment

Monorepo Structure

Understand the codebase organization

Testing Guide

Learn about testing practices

Code of Conduct

Read the full Code of Conduct
Thank you for contributing to Skiff! Your efforts help make privacy-first software accessible to everyone.

Build docs developers (and LLMs) love

Get started for freeTalk to us