diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index cd76012..3e4ac5b 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,20 +1,64 @@ # Description - - +Please describe the changes in this PR. Explain the problem you're solving or the feature you're adding. + + + +--- + +## Related Issue + +Closes # + + +--- + ## Type of Change -- [ ] **Bug fix** (non-breaking change which fixes an issue) -- [ ] **New feature** (non-breaking change which adds functionality) -- [ ] **Breaking change** (fix or feature that would cause existing functionality to not work as expected) -- [ ] **Documentation** -- [ ] **Performance improvement** +- [ ] Bug fix (fixes an issue without changing existing functionality) +- [ ] New feature (adds new functionality) +- [ ] Breaking change (changes that would cause existing functionality to work differently) +- [ ] Documentation update +- [ ] Performance improvement +- [ ] Refactoring (no behavior change) +- [ ] Dependencies update + +--- ## Checklist -- [ ] I have run `cargo fmt` to ensure consistent code style. -- [ ] I have run `cargo test` and all tests passed. -- [ ] I have added new tests that prove my fix is effective or that my feature works. -- [ ] I have updated the `README.md` (if applicable). +- [ ] My code follows the project style guidelines (ran `cargo fmt`) — if applicable +- [ ] I've linted my code (ran `cargo clippy`) — if applicable +- [ ] I've written and run tests (`cargo test` passes) — if applicable +- [ ] I've added tests for new functionality or bug fixes — if applicable +- [ ] I've updated documentation (README, code comments, etc.) — if applicable +- [ ] I've updated the changelog/release notes — if applicable +- [ ] My commits follow the Conventional Commits specification +- [ ] I've reviewed my own code before submitting + +--- + +## Breaking Changes + +If this introduces breaking changes, please describe: + +- What changed and why +- How users should migrate their code + + + +--- ## Performance Impact + +- [ ] No performance impact +- [ ] Performance improved (describe improvements) +- [ ] Performance regressed (describe regression and mitigation) + +Details: + +--- + +## Screenshots / Demo + + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 208bcac..3369b32 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,88 +1,76 @@ # CONTRIBUTING GUIDELINES +Thanks for your interest in contributing! We'd love to have your help improving +this project. + ## Getting Started -If you are thinking of contributing to this project, you can get started by -forking the project. Detailed instructions are as follows. +> [!IMPORTANT] +> We ask that you follow the Conventional Commits specification for commit +> messages. Check out [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) +> to learn more. +> +> Here are some examples: +> +> - `feat(cli): add --timeout option to set request timeout` +> - `fix(download): retry on 429 Too Many Requests with backoff` +> - `docs(readme): update usage examples for subcommands` +> - `style: apply rustfmt formatting (no behavior change)` + +Want to contribute? Just fork the project and follow these steps: 1. Fork the Project 2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`) -3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)` +3. Commit your Changes (`git commit -m 'feat(topic): Add some AmazingFeature'`)` 4. Push to the Branch (`git push origin feature/AmazingFeature`) 5. Open a Pull Request -> [!NOTE] -> _Instructions on creating pull requests is explained in_ -> _[Submitting a Pull Request](#submitting-a-pull-request) section below._ +### Submitting a Pull Request -## Code of Conduct +Before submitting your PR, make sure your branch is up to date with the base +branch and that there are no merge conflicts. -### Purpose +- Go to your forked repository on GitHub +- Update your main branch to match the latest upstream changes +- Create a new branch for your changes +- Submit a PR with a clear title and description +- You can use the template at `.github/PULL_REQUEST_TEMPLATE.md` as a guide -This Code of Conduct outlines the expected behavior for all participants in the -community. The goal is to foster a positive, inclusive, and respectful -environment where everyone feels welcome and valued. - -### Expected Behavior - -- **Respect**: Treat everyone with respect, regardless of their background or - opinions. -- **Inclusivity**: Promote a welcoming and inclusive environment for all. -- **Constructive Communication**: Engage in constructive and respectful - discussions, avoiding personal attacks or insults. -- **Openness**: Be open to feedback and criticism, and be willing to learn from - others. -- **Collaboration**: Work together towards the common goal of improving the - project. - -### Prohibited Behavior - -- **Harassment**: Any form of harassment, including but not limited to: - - Sexual harassment - - Discrimination - - Threats - - Bullying -- **Hate Speech**: Language that promotes hatred or discrimination against any group of people. -- **Personal Attacks**: Attacks on a person's character or abilities. -- **Plagiarism**: Claiming credit for work that is not your own. +## Code of Conduct -> [!IMPORTANT] -> This Code of Conduct is a living document and may be updated from time to time. +### Purpose -## Submitting a Pull Request +This Code of Conduct sets expectations for how we treat each other in this +community. We're committed to creating a welcoming, inclusive, and respectful +space where everyone feels comfortable contributing. -- Navigate to your forked repository on GitHub. -- Click the "Compare & pull request" button. -- Add a descriptive title and provide details about your changes. - You can see the PR template at `.github/PULL_REQUEST_TEMPLATE.md` file. -- Submit the pull request. +### What We Expect -## Tagging a new version +Help us keep this community positive and collaborative by: -> [!IMPORTANT] -> New versions are generally tagged after completing milestones, and will -> probably be updated automatically with workflows in the future. The -> instruction below will be useful for developers to know how versions are -> being tagged in the project. +- Being respectful and professional with everyone +- Welcoming different perspectives and backgrounds +- Giving constructive feedback focused on ideas, not people +- Being open to feedback and learning from mistakes +- Helping each other and sharing knowledge freely -Install package `cargo-workspaces` +### Behavior We Don't Tolerate -```sh -cargo install cargo-workspaces -``` +We take these issues seriously and project maintainers will address them: -Run `cargo workspaces` or `cargo ws` command +- Harassment, bullying, threats, or abusive language of any kind +- Hate speech or dehumanizing comments based on who someone is +- Personal attacks, doxxing, or sharing someone's private information +- Taking credit for someone else's work -```sh -# major version -cargo ws version major +If you witness or experience any of these issues, please reach out to the +maintainers so we can address it promptly. -# minor version -cargo ws version minor +> [!IMPORTANT] +> This Code of Conduct is a living document and may be updated as needed. -# patch version -cargo ws version patch +## Licensing -# pre release version -cargo ws version minor --pre-id alpha -``` +When you submit a contribution, you're agreeing to license it under the +[Apache License](LICENSE). If you have questions or need a different licensing +arrangement, please open an issue or reach out to the maintainers first. diff --git a/Cargo.lock b/Cargo.lock index 5b88e2e..4dc11b3 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -261,7 +261,7 @@ checksum = "92773504d58c093f6de2459af4af33faa518c13451eb8f2b5698ed3d36e7c813" name = "embedded-minimal" version = "0.1.0" dependencies = [ - "furl-core", + "furl-core 0.9.0 (registry+https://github.com/rust-lang/crates.io-index)", "tokio", ] @@ -318,7 +318,7 @@ name = "furl-cli" version = "0.8.1" dependencies = [ "clap", - "furl-core", + "furl-core 0.9.0", "futures-util", "indicatif", "regex", @@ -338,6 +338,19 @@ dependencies = [ "tokio", ] +[[package]] +name = "furl-core" +version = "0.9.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f4076081a4c00b75a81ec453c71180962969e17e9773c7d01174caa5effcf778" +dependencies = [ + "futures-util", + "indicatif", + "regex", + "reqwest", + "tokio", +] + [[package]] name = "futures-channel" version = "0.3.32" @@ -833,7 +846,7 @@ dependencies = [ name = "no-indicator" version = "0.1.0" dependencies = [ - "furl-core", + "furl-core 0.9.0 (registry+https://github.com/rust-lang/crates.io-index)", "tokio", ] diff --git a/Cargo.toml b/Cargo.toml index d98305a..593bd5a 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -18,7 +18,7 @@ edition = "2024" [workspace.dependencies] tokio = { version = "1.52.3", features = ["rt-multi-thread", "macros"] } -furl-core = { version = "0.9.0-alpha.0", path = "crates/furl-core" } +furl-core = { version = "0.9.0", path = "crates/furl-core" } [workspace.metadata.workspaces] independent = true diff --git a/crates/furl-core/Cargo.toml b/crates/furl-core/Cargo.toml index f3bc616..9cc9a66 100644 --- a/crates/furl-core/Cargo.toml +++ b/crates/furl-core/Cargo.toml @@ -1,7 +1,7 @@ [package] name = "furl-core" description = "A fast, multithreaded downloader library built in Rust." -version="0.9.0" +version = "0.9.0" edition.workspace = true license.workspace = true publish = true diff --git a/examples/embedded-minimal/Cargo.toml b/examples/embedded-minimal/Cargo.toml index fca2311..82ae5aa 100644 --- a/examples/embedded-minimal/Cargo.toml +++ b/examples/embedded-minimal/Cargo.toml @@ -5,7 +5,10 @@ edition = "2024" publish = false [dependencies] -# instead of using the workspace, you should use version from crates.io for your application -# example: furl-cli = "0.8.0" -furl-core = { path = "../../crates/furl-core", features = ["progress"] } +# For local development in the repository, uncomment the path below: +# furl-core = { path = "../../crates/furl-core", features = ["progress"] } + +# For standalone use (outside the repository), use the crates.io version: +furl-core = { version = "0.9.0", features = ["progress"] } + tokio = { workspace = true, features = ["rt-multi-thread", "macros"] } diff --git a/examples/embedded-minimal/README.md b/examples/embedded-minimal/README.md new file mode 100644 index 0000000..eb1346c --- /dev/null +++ b/examples/embedded-minimal/README.md @@ -0,0 +1,59 @@ +# Embedded Minimal Example + +This example demonstrates how to embed `furl-core` in a Rust application with visual progress reporting. + +## Running This Example + +### Inside the Repository + +If you cloned the entire `furl-cli` repository, you can run: + +```bash +cargo run -p embedded-minimal +``` + +This uses the local path dependency to `furl-core`, so you'll always be working with the latest code from the repository. + +### Standalone / Outside the Repository + +To use this example as a standalone project or copy it elsewhere, update `Cargo.toml`: + +**Current (uses crates.io):** + +```toml +furl-core = { version = "0.9.0", features = ["progress"] } +``` + +If you want to use the local version while developing, change to: + +```toml +furl-core = { path = "../../crates/furl-core", features = ["progress"] } +``` + +Then run: + +```bash +cargo run +``` + +## What This Example Shows + +- Creating a `Downloader` instance with a URL +- Setting up `GraphicalProgressReporter` for visual progress feedback +- Configuring chunk size for parallel downloads (5 MB in this example) +- Running the download asynchronously with 4 worker threads +- Basic error handling for download operations + +## Dependencies + +- `furl-core` — The multithreaded download engine (with `progress` feature for visual bars) +- `tokio` — Async runtime for concurrent operations + +## Customization + +You can modify the example by: + +- Changing the URL to download different files +- Adjusting `set_max_chunk_size()` for different chunk sizes +- Modifying the thread count in `download()` for more/fewer parallel workers +- Implementing your own `ProgressReporter` trait for custom progress handling diff --git a/examples/no-indicator/Cargo.toml b/examples/no-indicator/Cargo.toml index 18ac24b..3d7648c 100644 --- a/examples/no-indicator/Cargo.toml +++ b/examples/no-indicator/Cargo.toml @@ -5,5 +5,10 @@ edition = "2024" publish = false [dependencies] -furl-core = { path = "../../crates/furl-core" } +# For local development in the repository, uncomment the path below: +# furl-core = { path = "../../crates/furl-core" } + +# For standalone use (outside the repository), use the crates.io version: +furl-core = { version = "0.9.0" } + tokio = { workspace = true, features = ["rt-multi-thread", "macros"] } diff --git a/examples/no-indicator/README.md b/examples/no-indicator/README.md new file mode 100644 index 0000000..ab2be30 --- /dev/null +++ b/examples/no-indicator/README.md @@ -0,0 +1,70 @@ +# No-Indicator Example + +This example demonstrates how to use `furl-core` for headless downloads without any visual progress reporting — ideal for servers, background jobs, or headless applications. + +## Running This Example + +### Inside the Repository + +If you cloned the entire `furl-cli` repository, you can run: + +```bash +cargo run -p no-indicator +``` + +This uses the local path dependency to `furl-core`, so you'll always be working with the latest code from the repository. + +### Standalone / Outside the Repository + +To use this example as a standalone project or copy it elsewhere, update `Cargo.toml`: + +**Current (uses crates.io):** + +```toml +furl-core = { version = "0.9.0" } +``` + +If you want to use the local version while developing, change to: + +```toml +furl-core = { path = "../../crates/furl-core" } +``` + +Then run: + +```bash +cargo run +``` + +## What This Example Shows + +- Creating a `Downloader` with **no progress reporter** (silent operation) +- Using `NoopReporter` implicitly for headless/background downloads +- Setting up chunk size configuration for parallel downloads +- Running downloads without any terminal output or visual feedback +- Minimal dependencies — only `furl-core` and `tokio` + +## Use Cases + +This pattern is ideal for: + +- **Server-side downloads** — background download jobs without UI +- **Batch processing** — downloading multiple files silently +- **Game engines** — asset downloads without terminal output +- **Embedded systems** — minimal logging and no progress bars +- **Testing** — simple, reproducible download behavior + +## Customization + +You can extend this example by: + +- Implementing your own `ProgressReporter` trait for custom logging or metrics +- Adding error handling and retry logic +- Logging download stats after completion +- Integrating with a metrics system or monitoring service +- Adjusting thread count for your specific use case + +## Dependencies + +- `furl-core` — The multithreaded download engine (without the `progress` feature for lean dependencies) +- `tokio` — Async runtime for concurrent operations