Skip to content

Latest commit

 

History

History
369 lines (264 loc) · 9.01 KB

CONTRIBUTING.md

File metadata and controls

369 lines (264 loc) · 9.01 KB

Contributing to docs.plus

Thank you for your interest in contributing to docs.plus! 🎉 This document provides guidelines and instructions for contributing to the project.

📋 Table of Contents

🤝 Code of Conduct

By participating in this project, you agree to maintain a respectful and inclusive environment for all contributors. Be kind, constructive, and professional in all interactions.

🚀 Getting Started

Prerequisites

Before you begin, ensure you have:

  • 🐳 Docker & Docker Compose v2+ - Install
  • 🚀 Bun >=1.3.7 - Install
  • 📦 Node.js >=24.11.0 (for some tooling)
  • 🗄️ Supabase CLI - Install
  • Git - Install

Fork and Clone

  1. Fork the repository on GitHub
  2. Clone your fork: 
    git clone https://github.com/YOUR_USERNAME/docs.plus.git
cd docs.plus
  3. Add upstream remote: 
    git remote add upstream https://github.com/docs-plus/docs.plus.git

💻 Development Setup

1. Install Dependencies

bun install

1.5 Run Doctor (Optional)

Check your environment is correctly set up:

bun run doctor

2. Environment Configuration

cp .env.example .env.development

Update .env.development with your local configuration. See .env.example for all available variables.

3. Initialize Supabase

make supabase-start

Then follow the Supabase setup instructions in the README.md.

4. Start Development Environment

make up-dev

This starts all services:

✏️ Making Changes

Branch Naming

Create a new branch for your changes:

git checkout -b type/description

Branch naming conventions:

  • feature/ - New features
  • fix/ - Bug fixes
  • refactor/ - Code refactoring
  • docs/ - Documentation updates
  • test/ - Test additions/updates
  • chore/ - Maintenance tasks

Examples:

  • feature/add-dark-mode
  • fix/resolve-memory-leak
  • docs/update-api-docs

Commit Messages

We follow Conventional Commits format:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting, etc.)
  • refactor: Code refactoring
  • test: Adding or updating tests
  • chore: Maintenance tasks

Examples:

feat(webapp): add dark mode toggle
fix(api): resolve memory leak in document sync
docs(readme): update installation instructions
refactor(editor): simplify toolbar component

🎨 Code Style

Formatting

We use Prettier for code formatting. Format your code before committing:

bun run format

Or check formatting:

bun run format:check

Linting

We use ESLint for code quality. Fix linting issues:

bun run lint:fix

Git Hooks (Husky)

We use Husky to enforce local quality gates before code reaches remote branches.

  • .husky/* contains lightweight wrapper scripts.
  • scripts/hooks/*.sh contains the actual hook logic.
  • Active hooks:
    • pre-commit: runs bun run lint:staged (staged-file lint/format checks)
    • commit-msg: validates commit message format
    • pre-push: runs selective build checks and always runs bun run check for every push
    • post-merge: runs bun install when package.json or bun.lock changes

You can trigger hooks manually:

# pre-commit (staged file checks)
sh .husky/pre-commit

# commit message validation
echo "feat(webapp): verify hook docs" > /tmp/commit-msg.txt
sh .husky/commit-msg /tmp/commit-msg.txt

# pre-push simulation (no real push)
printf 'refs/heads/feature/demo 0000000000000000000000000000000000000000 refs/heads/feature/demo 0000000000000000000000000000000000000000\n' | \
  sh .husky/pre-push origin https://github.com/docs-plus/docs.plus.git

TypeScript

  • Use TypeScript for all new code
  • Avoid any types - use proper types or unknown
  • Enable strict mode in your IDE
  • Run type checking: bun run build (will fail on type errors)

🧪 Testing

Unit Tests

Run unit tests with Jest:

cd packages/webapp
bun test

E2E Tests

Run Cypress E2E tests:

# Interactive mode
bun run cypress:open

# Headless mode
bun run cypress:run

Test Coverage

Aim for good test coverage, especially for:

  • Critical business logic
  • API endpoints
  • Complex components
  • Utility functions

Writing Tests

  • Write tests alongside your code
  • Test behavior, not implementation
  • Use descriptive test names
  • Keep tests simple and focused

📤 Submitting Changes

Before Submitting

  1. Update your fork:

    git fetch upstream
git checkout main
git merge upstream/main

  2. Rebase your branch (if needed):

    git checkout your-branch
git rebase main

  3. Run checks (lint + format + types):

    bun run check

    This is also enforced automatically by pre-push for every git push.

    Or individually:

    bun run lint
bun run format:check
bun run typecheck:webapp
bun run typecheck:admin
bun run typecheck:backend

  4. Test locally:

    • Start the development environment
    • Test your changes manually
    • Verify no regressions

Creating a Pull Request

  1. Push your branch:

    git push origin your-branch

  2. Create a PR on GitHub:

    • Use a clear, descriptive title
    • Fill out the PR template (if available)
    • Reference any related issues
    • Add screenshots/GIFs for UI changes

  3. PR Checklist:

    • Code follows style guidelines
    • Tests pass locally
    • Documentation updated (if needed)
    • No console errors/warnings
    • Changes are backward compatible (if applicable)

PR Review Process

  • Maintainers will review your PR
  • Address feedback promptly
  • Keep PRs focused and reasonably sized
  • Be open to suggestions and improvements

📁 Project Structure

docs.plus/
├── packages/
│   ├── webapp/              # 🌐 Next.js frontend
│   │   ├── src/
│   │   │   ├── components/  # React components
│   │   │   ├── api/         # API clients
│   │   │   ├── hooks/       # React hooks
│   │   │   ├── stores/      # State management
│   │   │   └── utils/       # Utility functions
│   │   └── cypress/         # E2E tests
│   ├── hocuspocus.server/   # ⚡ REST API, WebSocket, Workers
│   │   ├── src/
│   │   │   ├── api/         # REST API routes & controllers
│   │   │   ├── lib/         # Shared libraries (email, push, etc.)
│   │   │   ├── middleware/  # Hono middleware
│   │   │   └── config/      # Configuration & env schemas
│   │   └── prisma/          # Prisma schema & migrations
│   ├── admin-dashboard/     # 🛠️ Admin interface (Next.js)
│   ├── supabase/            # 🗄️ Supabase configuration
│   │   └── scripts/         # SQL migration scripts
│   └── extension-*/         # 🔌 TipTap extensions
├── .github/workflows/       # 🔄 CI/CD pipelines
├── docker-compose.dev.yml   # 🐳 Development setup
├── docker-compose.prod.yml  # 🚀 Production setup
└── Makefile                 # 🛠️ Build commands

🎯 Areas for Contribution

We welcome contributions in all areas:

  • 🐛 Bug Fixes: Fix issues reported in GitHub Issues
  • ✨ Features: Implement new features (check Issues for ideas)
  • 📚 Documentation: Improve docs, add examples, fix typos
  • 🧪 Tests: Add tests, improve coverage
  • 🎨 UI/UX: Improve design, accessibility, user experience
  • ⚡ Performance: Optimize code, reduce bundle size
  • 🔒 Security: Report or fix security issues

💡 Getting Help

🙏 Thank You!

Your contributions make docs.plus better for everyone. Thank you for taking the time to contribute! ❤️

Questions? Feel free to ask in Discord or open an issue on GitHub.