CalvinBackup/donutbrowser
1
0
Fork 0
mirror of https://github.com/zhom/donutbrowser.git synced 2026-04-22 03:46:43 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: contributing

Browse Source
This commit is contained in:
zhom
2026-03-24 05:20:30 +04:00
parent 21bc1de298
commit e9c4e32df2
1 changed files with 61 additions and 157 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONTRIBUTING.md
+61 -157
View File
@@ -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