Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
115 lines (78 loc) · 3.83 KB

CONTRIBUTING.md

File metadata and controls

115 lines (78 loc) · 3.83 KB

Contributing to Nook

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

AI Assistance Notice

If you are using any kind of AI assistance to contribute, this must be disclosed in your pull request, commit, or issue, including the extent to which AI assistance was used (e.g. docs only vs. code generation). If PR responses, commit messages, or comments are being generated by an AI, please disclose that as well.

As a small exception, trivial tab-completion doesn't need to be disclosed, so long as it is limited to single keywords or short phrases.

When using AI assistance, we expect contributors to understand the code that is produced and be able to answer critical questions about it. It isn't a maintainer's job to review a PR so broken that it requires significant rework to be acceptable.

Please be respectful to maintainers and disclose AI assistance.

🚀 Development Setup

  1. Clone the repository

    git clone https://github.com/yourusername/Nook.git
cd Nook

  2. Switch to the dev branch

    git checkout dev

  3. Open in Xcode

    open Nook.xcodeproj

  4. Build and run

    • Select your target device/simulator
    • Press Cmd + R to build and run

📝 Code Style & Standards

Conventions

  • Follow existing SwiftUI/AppKit patterns in the codebase
  • Use the established file organization structure
  • Prefer modern Swift/SwiftUI APIs when possible

Compatibility & OS Versions

  • Maintain backward compatibility: The current minimum deployment target is macOS 15.5
  • New features requiring newer OS versions should use @available or #if available checks to preserve compatibility
  • Discuss before raising minimum version: If a feature would significantly benefit from raising the minimum OS version, open an issue to discuss the trade-offs before implementation

📋 Pull Request Process

Before You Start

  • Check for duplicates: Search existing issues and PRs to ensure no one is already working on the same feature or bug
  • Avoid duplicate work: Comment on relevant issues to indicate you're working on them
  • For major changes, consider opening an issue first to discuss the approach

Creating Pull Requests

IMPORTANT: All development work must be done on the dev branch:

  1. Create your branch from dev, not main:

    git checkout dev
git pull origin dev
git checkout -b feature/your-feature-name

  2. Make your changes and commit them with clear, descriptive messages

  3. Push to your fork:

    git push origin feature/your-feature-name

  4. Open a Pull Request to the dev branch, not main

    • Provide a clear description of the changes
    • Reference any related issues
    • Include screenshots or videos for UI changes
    • Disclose any AI assistance used (see AI Assistance Notice above)

  5. Respond to review feedback promptly and constructively

🐛 Issue Reporting

Bug Reports

Be descriptive and thorough. Include:

  • macOS version
  • Nook version
  • Clear steps to reproduce the issue
  • Expected vs actual behavior
  • Screenshots if applicable
  • Relevant console/error messages

Feature Requests

Provide detailed context. Include:

  • Clear description of the feature and its use case
  • Explain how it fits with Nook's goals (fast, secure, beautiful)
  • Consider implementation complexity and user impact
  • Check that similar functionality doesn't already exist

💬 Community Guidelines

  • Be respectful and constructive
  • Help maintain a welcoming environment for all contributors
  • Focus on the code and ideas, not individuals

License

By contributing to Nook, you agree that your contributions will be licensed under the GPL-3.0 License.