# Contributing Wrangler is an open source project because we believe that folks should have access, insight, and the opportunity to contribute to their developer tools. Wrangler is also a product delivered by Cloudflare, so it's important to clarify how we think about issue triage and contributions. If you want to learn about how to get started developing Wrangler, [click here](#Developing-Wrangler) ## People Wrangler is owned by the [Cloudflare Workers](https://workers.cloudflare.com) Team and maintained by community members like you! The core maintainers are @EverlastingBugstopper and @ashleymichal, and everything that gets merged must be approved by at least one team member. ## Developing Wrangler ### Get started To get started with developing Wrangler, we recommend that you first get [up to speed with Wrangler](https://developers.cloudflare.com/workers/quickstart). Then, get up to speed with the [basics of Rust](https://www.rust-lang.org/learn/get-started). (You'll need to install `rustup` where we're going). ### Build Wrangler from source To build Wrangler from source, fork the repo, clone it, and `cd wrangler`. To run the test suite, run `cargo test`. To quickly test a command, for example `wrangler init`, run `cargo run -- init`. This will compile a "debug" binary, then run it, passing in all arguments after `--`. It is important to note that many Wrangler commands depend on a `wrangler.toml` in the current working directory. It is advised to keep a test project somewhere with an active `wrangler.toml` to exercise your code. ### Run Wrangler during development There are many ways to build and execute a development version of Wrangler, in addition to using `cargo run`: `cargo build` will produce a local binary at `./target/debug/wrangler` that you can execute just by calling it by path. `cargo install --debug --path .` will replace any globally installed wrangler with the one you've just built from source. You can read more about cargo [here](https://doc.rust-lang.org/cargo/), just find something that works for you. ### Module System Each of the commands supported by Wrangler have entrypoints in [./src/commands](./src/commands). It's useful to understand the [module system](https://doc.rust-lang.org/rust-by-example/mod.html) if you will be adding new commands or need to refactor/organize imports. ### Notable external libraries #### Command-line argument parsing (clap) The primary framework we use for developing Wrangler is called [clap](https://clap.rs), which provides fast and structured argument parsing. This is how different features are exposed to users, and most of that logic lives in [main.rs](./src/main.rs). #### API calls (cloudflare-rs) When developing a new feature for Wrangler, it's quite common to need to make API calls. The way we do this is by submitting a PR to [cloudflare-rs](https://github.com/cloudflare/cloudflare-rs) and releasing a new version of that library to depend on. There are some legacy endpoints that we use our own client for, but the goal is to eventually move everything to cloudflare-rs. All endpoint calls should be made with the clients in [./src/http](./src/http). ### Figure out where to start If you're working on a specific issue, make sure there is buy-in from the Wrangler team before starting, and feel free to ask where you should start. We're more than happy to help! ### Requirements for merging a PR ### Passing tests When adding features or fixing bugs, we'd love if you would add a test! There are two types of tests in Wrangler, integration and unit tests. To execute tests, you can run `cargo test`. You can read more about testing [here](https://doc.rust-lang.org/rust-by-example/testing.html). All tests must pass when submitting a new PR, this is enforced by our GitHub Actions runners, which run each test on Windows, MacOS, and Linux. ### Proper formatting You must run `cargo fmt` on your code before CI will allow you to merge your PR. ## Primary Issue Triage Within 3 days, any incoming issue should be triaged. Triage involves: - reading the issue and requesting any further information - always thank the user for submitting - assigning appropriate labels ### Labelling - each issue should have a `status` label and a `category` label, and they should be kept up to date - once design has been settled for an issue, please label with `status - PR welcome` - each issue from non-team members should be labelled `user report` (issue templates assign this automatically) - subject labels and other call to actions are nice to have - if an issue seems easy to tackle, please label with `good first issue` so new contributors can use it to ramp up ### Assignment - if the issue will require a large amount of back and forth between the reporter and the team assign a single team member to manage the conversation ## Product Issue Triage Once a week, the team holds the Wrangler Contributors meeting. This is where we assign work and update our plans for the milestones and releases. ### Assignment and Milestones - assign all issues for the next two releases a milestone - assign all issues for the current milestone a person to take point ## Pull Request Triage Within 3 days, all incoming Community PRs should be triaged. If a team member opens a PR it should be triaged immediately upon open by the PR author. ### Labelling - All work-in-progress PRs should be labelled `work in progress` and the title should be annotated [WIP] for easy scanning. No WIP PRs will be reviewed until the annotations are removed. - All PRs that need to be reviewed should be labelled `needs review` until they have received all required reviews. - All PRs should be labelled with a changelog label: `BREAKING`, `feature`, `fix`, `maintenance`, `docs`, `N/A` - All PRs that are ready for review should be tagged with the appropriate release milestone ### Merging - All PRs should be merged with a Merge Commit. We recommend that folks rebase into a small number of task driven commits. This is enforced more heavily for team members than community members. Be reasonable. - All PRs should be labelled with the current milestone before merging. If a PR for an issue labelled with a different milestone is to be merged, update the issue milestone as well.