From e9c4e32df297a3c168d95826ea50aca068446ad2 Mon Sep 17 00:00:00 2001 From: zhom <2717306+zhom@users.noreply.github.com> Date: Tue, 24 Mar 2026 05:20:30 +0400 Subject: [PATCH] docs: contributing --- CONTRIBUTING.md | 218 ++++++++++++++---------------------------------- 1 file changed, 61 insertions(+), 157 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 38fcf31..ad05943 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,194 +1,98 @@ # Contributing to Donut Browser -Contributions are welcome and always appreciated! 🍩 - -To begin working on an issue, simply leave a comment indicating that you're taking it on. There's no need to be officially assigned to the issue before you start. +Contributions are welcome! To start working on an issue, leave a comment indicating you're taking it on. ## Before Starting -Do keep in mind before you start working on an issue / posting a PR: - -- Search existing PRs related to that issue which might close them -- Confirm if other contributors are working on the same issue -- Check if the feature aligns with the project's roadmap and goals +- Search existing PRs related to that issue +- Confirm no other contributors are working on the same issue +- Check if the feature aligns with the project's goals ## Contributor License Agreement -By contributing to Donut Browser, you agree that your contributions will be licensed under the same terms as the project. You must agree to the [Contributor License Agreement](CONTRIBUTOR_LICENSE_AGREEMENT.md) before your contributions can be accepted. This agreement ensures that: - -- Your contributions can be used in the open source version of Donut Browser (licensed under AGPL-3.0) -- Donut Browser can offer commercial licenses for the software, including your contributions -- You retain all rights to use your contributions for any other purpose - -When you submit your first pull request, you acknowledge that you agree to the terms of the Contributor License Agreement. - -## Tips & Things to Consider - -- PRs with tests are highly appreciated -- Avoid adding third party libraries, whenever possible -- Unless you are helping out by updating dependencies, you should not be uploading your lock files or updating any dependencies in your PR -- If you are unsure where to start, open a discussion to get pointed to a good first issue +By contributing, you agree your contributions will be licensed under the same terms as the project. See [Contributor License Agreement](CONTRIBUTOR_LICENSE_AGREEMENT.md). This ensures contributions can be used in the open source version (AGPL-3.0) and commercially licensed. You retain all rights to use your contributions elsewhere. ## Development Setup -### Using Nix - -If you have [Nix](https://nixos.org/) installed, you can skip the manual setup below and simply run: +### Using Nix (recommended) ```bash -nix develop -# or if you use direnv -direnv allow +nix run .#setup # Install dependencies +nix run .#tauri-dev # Start development server +nix run .#test # Run all checks ``` -This will provide Node.js, Rust, and all necessary system libraries. +Or enter the dev shell: `nix develop` ### Manual Setup -Ensure you have the following dependencies installed: - -- Node.js (see `.node-version` for exact version) -- pnpm package manager -- Latest Rust and Cargo toolchain -- [Tauri prerequisites guide](https://v2.tauri.app/start/prerequisites/). - -## Run Locally - -After having the above dependencies installed, proceed through the following steps to setup the codebase locally: - -1. **Fork the project** & [clone](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) it locally. - -2. **Create a new separate branch.** - - ```bash - git checkout -b feature/my-feature-name - ``` - -3. **Install frontend dependencies** - - ```bash - pnpm install - ``` - -4. **Start the development server** - - ```bash - pnpm tauri dev - ``` - -This will start the app for local development with live reloading. - -## Code Style & Quality - -The project uses several tools to maintain code quality: - -- **Biome** for JavaScript/TypeScript linting and formatting -- **Clippy** for Rust linting -- **rustfmt** for Rust formatting - -### Before Committing - -Run these commands to ensure your code meets the project's standards: +Requirements: +- Node.js (see `.node-version`) +- pnpm +- Rust + Cargo (latest stable) +- [Tauri v2 prerequisites](https://v2.tauri.app/start/prerequisites/) ```bash -# Format and lint frontend code -pnpm format:js - -# Format and lint Rust code -pnpm format:rust - -# Run all linting -pnpm lint +git checkout -b feature/my-feature-name +pnpm install +pnpm tauri dev ``` -## Building +## Quality Checks -It is crucial to test your code before submitting a pull request. Please ensure that you can make a complete production build before you submit your code for merging. +Run before every commit: ```bash -# Build the frontend -pnpm build - -# Build the backend -cd src-tauri && cargo build - -# Build the Tauri application -pnpm tauri build +pnpm format && pnpm lint && pnpm test ``` -Make sure the build completes successfully without errors. +This runs: +- **Biome** — JS/TS linting and formatting +- **Clippy + rustfmt** — Rust linting and formatting +- **typos** — Spellcheck (allowlist in `_typos.toml`) +- **CodeQL** — Security analysis (JS, Actions, Rust) — runs in CI +- **Unit tests** — 330+ Rust tests +- **Integration tests** — proxy, sync e2e -## Testing +### Running CodeQL locally -- Always test your changes on the target platform -- Verify that existing functionality still works -- Add tests for new features when possible +```bash +# Install: brew install codeql +codeql pack download codeql/javascript-queries codeql/rust-queries + +# JavaScript +codeql database create /tmp/codeql-js --language=javascript --source-root=. +codeql database analyze /tmp/codeql-js --format=sarifv2.1.0 --output=/tmp/js.sarif codeql/javascript-queries + +# Rust +codeql database create /tmp/codeql-rust --language=rust --source-root=. +codeql database analyze /tmp/codeql-rust --format=sarifv2.1.0 --output=/tmp/rust.sarif codeql/rust-queries +``` + +## Key Rules + +- **Translations**: Any UI text changes must be reflected in all 7 locale files (`src/i18n/locales/`) +- **Tauri commands**: If you modify Tauri commands, the `test_no_unused_tauri_commands` test will catch unused ones +- **No hardcoded colors**: Use theme CSS variables (see `src/lib/themes.ts`), never Tailwind color classes like `text-red-500` +- **No lock file changes**: Don't update `pnpm-lock.yaml` or `Cargo.lock` unless updating dependencies is the purpose of the PR +- **AGPL-3.0**: This project is AGPL-licensed. Derivatives must be open source with the same license ## Pull Request Guidelines -🎉 Now that you're ready to submit your code for merging, there are some points to keep in mind: +- Fill the PR description template +- Reference related issues (`Fixes #123` or `Refs #123`) +- Include screenshots/videos for UI changes +- Ensure "Allow edits from maintainers" is checked -### PR Description +## Architecture -- Fill your PR description template accordingly -- Have an appropriate title and description -- Include relevant screenshots for UI changes. If you can include video/gifs, it is even better. -- Reference related issues - -### Linking Issues - -If your PR fixes an issue, add this line **in the body** of the Pull Request description: - -```text -Fixes #00000 -``` - -If your PR is referencing an issue: - -```text -Refs #00000 -``` - -### PR Checklist - -- [ ] Code follows the project's style guidelines -- [ ] I have performed a self-review of my code -- [ ] I have commented my code, particularly in hard-to-understand areas -- [ ] I have made corresponding changes to the documentation -- [ ] My changes generate no new warnings -- [ ] I have added tests that prove my fix is effective or that my feature works -- [ ] New and existing unit tests pass locally with my changes -- [ ] Any dependent changes have been merged and published - -### Options - -- Ensure that "Allow edits from maintainers" option is checked - -## Architecture Overview - -Donut Browser is built with: - -- **Frontend**: Next.js React application -- **Backend**: Tauri (Rust) for native functionality -- **Node.js Sidecar**: `nodecar` binary for access to JavaScript ecosystem -- **Build System**: GitHub Actions for CI/CD - -Understanding this architecture will help you contribute more effectively. +- **Frontend**: Next.js (React) — `src/` +- **Backend**: Tauri (Rust) — `src-tauri/src/` +- **Proxy Worker**: Detached process for proxy tunneling — `src-tauri/src/bin/proxy_server.rs` +- **Sync**: Cloud sync via S3-compatible storage — `src-tauri/src/sync/`, `donut-sync/` +- **Browsers**: Camoufox (Firefox-based) and Wayfern (Chromium-based) ## Getting Help -- **Issues**: Use for bug reports and feature requests -- **Discussions**: Use for questions and general discussion -- **Pull Requests**: Use for code contributions - -## Code of Conduct - -Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms. - -## Recognition - -All contributors will be recognized! The project uses the all-contributors specification to acknowledge everyone who contributes. - ---- - -Thank you for contributing to Donut Browser! 🍩✨ +- **Issues**: Bug reports and feature requests +- **Discussions**: Questions and general discussion