Skip to content
This repository has been archived by the owner on Aug 3, 2023. It is now read-only.

Adds Developing Wrangler section to Contribution Guide #1288

Merged
merged 1 commit into from
May 15, 2020
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 59 additions & 15 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,24 +5,27 @@ 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

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

Expand All @@ -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.
Expand All @@ -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

Expand All @@ -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).

EverlastingBugstopper marked this conversation as resolved.
Show resolved Hide resolved
### 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.