Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
133 lines (94 loc) · 5.08 KB

CONTRIBUTING.md

File metadata and controls

133 lines (94 loc) · 5.08 KB
Raw

Contributing to NoteHand 🤝

Thank you for your interest in contributing to NoteHand! As an open-source project, we welcome improvements, bug fixes, features, and documentation enhancements.

Following these guidelines helps ensure a smooth, efficient process for everyone.

📋 Code of Conduct

By participating in this project, you agree to maintain a respectful, welcoming, and professional environment. Please read and follow our Code of Conduct in all interactions.

🛠️ Development Setup

To set up your local development environment, follow these steps:

  1. Fork the Repository: Fork NoteHand to your own GitHub account.
  2. Clone Locally: 
    git clone https://github.com/YOUR_USERNAME/NoteHand.git
cd NoteHand
  3. Install Dependencies: 
    npm install
  4. Configure environment files: Create a local configuration file: 
    cp .env.example .env.local
  5. Run Development Server: 
    npm run dev
    The application will be running at http://localhost:3000.

🌿 Branching Strategy

We use a simple branching model. Always create a branch off the main branch before editing code. Use prefixes to identify the type of changes:

  • feature/ — Add a new capability (e.g., feature/shape-auto-snapping).
  • fix/ — Fix a bug or issue (e.g., fix/pinch-zoom-ios-deadlock).
  • docs/ — Documentation updates (e.g., docs/add-contributing-guide).
  • refactor/ — Code cleanup or structural changes (e.g., refactor/zod-schema-definitions).
  • perf/ — Performance enhancements (e.g., perf/canvas-render-loops).
git checkout -b feature/your-feature-name

💬 Commit Message Guidelines

We enforce the Conventional Commits standard for clear, readable project histories:

<type>(<scope>): <short summary>

[optional body description]

Types

  • feat: A new feature.
  • fix: A bug fix.
  • docs: Documentation only changes.
  • style: Code formatting changes (spaces, semicolons) that do not affect functionality.
  • refactor: Code changes that neither fix a bug nor add a feature.
  • perf: A code change that improves performance.
  • test: Adding missing tests or correcting existing tests.
  • chore: Build process or auxiliary tool updates.

Examples

  • feat(canvas): add shape auto-recognition logic
  • fix(touch): prevent stale pointer entries on iOS Chrome
  • docs(readme): add self-hosting instructions

🐛 Issue Reporting

Before opening a new issue, please search the existing issues to see if it has already been reported.

🚀 Pull Request Process

When you are ready to submit your changes:

  1. Rebase & Lint: Ensure your code is up to date with the latest main branch, is formatted correctly, and compiles with zero TypeScript errors: 
    npm run lint
npm run build
  2. Push to your fork: 
    git push origin feature/your-feature-name
  3. Submit a Pull Request (PR): Open a PR against NoteHand's main branch.
  4. Use the PR Template: Fill out the generated PR Template completely, describing the bug/feature, testing performed, and checking off the pre-merge checklist.
  5. Review: Maintainers will review your PR and guide you if changes are needed before merging.

📏 Coding Style & Standards

To maintain code quality across NoteHand, please follow these guidelines:

  • TypeScript: Write fully-typed code. Avoid using any type signatures.
  • React Concurrent Rules: Ensure hooks, refs, and state are optimized. Do not bypass React render logic unless optimizing high-frequency render paths (like drawing overlays).
  • Performance: Check for layout reflows and memory leaks (such as unremoved event listeners in useEffect).
  • Security: Validate external parameters or storage data using the Zod validation schemas in src/security/validation.ts. Sanitize any media using processAndSanitizeImage in src/security/sanitizer.ts.

🧪 Testing & Verification Expectations

Before submitting a Pull Request, you must verify your changes:

  1. Type check validation: Run npm run lint (tsc --noEmit) to verify that the TypeScript compiler finds no issues.
  2. Production build check: Run npm run build to verify the asset bundler and code splitting operate without compilation warnings or errors.
  3. Manual Test Matrix: Verify responsiveness across mobile, tablet, and desktop viewports, and confirm rendering in both light and dark appearance modes.