From 0c794a3c228564ced97474cf6701e542165c6293 Mon Sep 17 00:00:00 2001 From: Avery Harnish Date: Fri, 15 May 2020 13:45:14 -0500 Subject: [PATCH] Adds Developing Wrangler section --- CONTRIBUTING.md | 74 +++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 59 insertions(+), 15 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c3688ed46..abbdcde7b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,9 +5,11 @@ and the opportunity to contribute to their developer tools. Wrangler is also a p 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 with Wrangler, [click here](#Developing-Wrangler) + ## People -Wrangler is maintained by @ashleygwilliams, and her team, Workers Developer Experience. +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. ## Primary Issue Triage @@ -15,14 +17,15 @@ 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 -- label all issues coming from non-team members with `user report` -- labelling the category of the issue: `feature`, `external bug`, `bug`, `maintenance`, `docs`, `refactor`, `release` -- labelling the status of the issue: `needs design`, `needs docs`, `needs more info`, `needs repro`, `needs template`, `PR attached`, `PR welcome`, `waiting on response` -- optionally labelling a subject: `cargo install`, `kv`, `routes`, `site`, `webpack`, `workers runtime` -- optionally labelling other calls to action: `help wanted`, `question`, `good first issue` +- 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 @@ -31,20 +34,15 @@ Within 3 days, any incoming issue should be triaged. Triage involves: ## Product Issue Triage -Once a week, the team meets to do Product Triage. This is where we assign work and update +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. -### Labelling - -- labelling the priority of the issue: `critical`, `nice to have`, `low priority` -- labelling the status of the issue: Needs Design, PR Welcome - ### 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 +## 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. @@ -54,9 +52,10 @@ should be triaged immediately upon open by the PR author. - 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 +- 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` +- 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 @@ -65,3 +64,48 @@ should be triaged immediately upon open by the PR author. 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. + +## 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`. + +There are many ways to build and execute a development version of Wrangler: + +`cargo build` will produce a local binary at `./target/debug/wrangler` that you can execute. +`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](). 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. \ No newline at end of file