# Contributing to `browser-paths`
Thanks for your interest in improving `browser-paths`!
This is a small Rust crate, and even small contributions (docs, tests, bug reports) are very welcome.
---
## How to Get Help or Ask Questions
- **Bugs / issues**: Please open a GitHub issue with:
- A clear description of the problem
- The platform (Linux / macOS / Windows) and browser/channel affected
- Steps to reproduce
- Relevant logs or error messages (if any)
- **Feature requests**: Open an issue describing:
- The use case (why you need the feature)
- Rough idea of the API you’d like (if applicable)
Before filing a new issue, **search existing issues** to avoid duplicates.
---
## Development Setup
- **Prerequisites**:
- Rust toolchain (via `rustup`) – use the latest stable when possible
- Git
Clone the repo and run tests to make sure everything works on your machine:
```bash
git clone https://github.com/betterhyq/browser-paths.git
cd browser-paths
cargo test
```
---
## Running Tests and Linting
- **Unit tests**:
```bash
cargo test
```
- **Formatting** (required before submitting a PR):
```bash
cargo fmt
```
- **Clippy** (recommended):
```bash
cargo clippy --all-targets --all-features -- -D warnings
```
Please make sure that:
- `cargo fmt` produces no changes
- `cargo test` passes
- `cargo clippy` does not emit warnings (or you have a good reason and explain it in the PR)
---
## Coding Guidelines
- **Language**: Rust, using idiomatic, stable Rust features.
- **Style**:
- Follow `rustfmt` defaults.
- Prefer small, focused functions and clear naming.
- Keep platform‑specific logic (Linux / macOS / Windows) clear and well‑commented.
- **Error handling**:
- Public helpers should continue to return `Option<PathBuf>`; avoid panics in library code.
- Favor explicit handling of “not installed / not found” over silently ignoring failures.
If you’re unsure about a design decision, mention alternatives you considered in the PR description.
---
## Adding / Changing Functionality
When you add or change behavior:
1. **Start with an issue**
- For non‑trivial changes, open an issue to discuss the proposal first.
2. **Write or update tests**
- Add tests that cover:
- Successful path discovery on the relevant platform(s)
- Failure cases (e.g., when a browser/channel is not installed)
- When platform‑specific behavior is hard to test automatically, add comments that describe what has been manually verified.
3. **Update documentation**
- Update `README.md` if you:
- Add new public functions
- Change behavior or semantics of existing functions
- Update doc comments on any new or modified public APIs.
---
## Pull Request Process
1. **Fork** the repository and create a branch:
```bash
git checkout -b my-feature-branch
```
2. **Make your changes**, keeping commits reasonably small and well‑described.
3. **Run checks** locally:
```bash
cargo fmt
cargo clippy --all-targets --all-features -- -D warnings
cargo test
```
4. **Open a Pull Request**:
- Link to any related issues (`Closes #123`).
- Describe:
- What changed
- Why it changed
- How you tested it (commands, platforms, browser channels)
- If the change affects only certain platforms, call that out explicitly.
5. **Review and iteration**:
- Be ready to adjust code based on maintainer feedback.
- Keep the conversation friendly and focused on the code.
---
## Platform and Browser Coverage
This crate targets:
- **Platforms**: Linux, macOS, Windows
- **Browsers**: Chrome & Edge (Stable / Beta / Dev / Canary)
If your change is platform‑specific:
- Clearly state which platform(s) you tested on.
- When possible, include notes in tests or comments to help others extend support to more platforms.
---
## License
By contributing to `browser-paths`, you agree that your contributions will be licensed under the same license as the project, the **MIT License** (see [LICENSE](LICENSE)).