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

Commit

Permalink
Adds Developing Wrangler section
Browse files Browse the repository at this point in the history
  • Loading branch information
EverlastingBugstopper committed May 15, 2020
1 parent 5b3a641 commit 0c794a3
Showing 1 changed file with 59 additions and 15 deletions.
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).

### 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.

0 comments on commit 0c794a3

Please sign in to comment.