Skip to main content
Thank you for your interest in contributing to Nook! This guide will help you get started with contributing to the project.

​
AI assistance disclosure

If you are using any kind of AI assistance to contribute, you must disclose this in your pull request, commit, or issue, including the extent to which AI assistance was used (e.g., docs only vs. code generation).
Trivial tab-completion doesn’t need to be disclosed, as long as it is limited to single keywords or short phrases.
When using AI assistance, we expect you to:
  • Understand the code that is produced
  • Be able to answer critical questions about it
  • Ensure the code meets quality standards before submission
If PR responses, commit messages, or comments are being generated by an AI, please disclose that as well.
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.

​
Pull request process

​
Before you start

1

Check for duplicates

Search existing issues and PRs to ensure no one is already working on the same feature or bug.
2

Indicate your work

Comment on relevant issues to indicate you’re working on them and avoid duplicate work.
3

Discuss major changes

For major changes, consider opening an issue first to discuss the approach.

​
Creating pull requests

All development work must be done on the dev branch. PRs targeting main will not be accepted.
1

Create your branch from dev

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

Make your changes

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 dev

When opening your PR, make sure to:
  • Target 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
5

Respond to feedback

Respond to review feedback promptly and constructively.

​
Code style and standards

​
Conventions

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

​
Compatibility and 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

​
Issue reporting

​
Bug reports

Be descriptive and thorough when reporting bugs. 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 when requesting features. Include:
  • Clear description of the feature and its use case
  • Explanation of how it fits with Nook’s goals (fast, secure, beautiful)
  • Consideration of implementation complexity and user impact
  • Verification that similar functionality doesn’t already exist

​
Community guidelines

Nook is built by volunteers who contribute their time and expertise out of passion for creating great software. We appreciate everyone who takes time to contribute to making Nook better.
  • Be respectful and constructive
  • Help maintain a welcoming environment for all contributors
  • Focus on the code and ideas, not individuals
  • Show empathy toward other community members
For more details, see our Code of Conduct.

​
License

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

Build docs developers (and LLMs) love

Get started for freeTalk to us