Skip to content

Latest commit

 

History

History
226 lines (170 loc) · 9.23 KB

CONTRIBUTING.md

File metadata and controls

226 lines (170 loc) · 9.23 KB
Raw

Contributing

Wrangler2 is an open source project and we welcome contributions from you. Thank you!

Below you can find some guidance on how to be most effective when contributing to the project.

Getting started

Set up your environment

Wrangler2 is built and run on the Node.js JavaScript runtime.

  • Install the latest LTS version of Node.js - we recommend using a Node version manager like nvm.
  • Install a code editor - we recommend using VS Code.
  • Install the git version control tool.

Fork and clone this repository

Any contributions you make will be via Pull Requests on GitHub developed in a local git repository and pushed to your own fork of the repository.

  • Ensure you have created an account on GitHub.
  • Create your own fork of this repository.
  • Clone your fork to your local machine 
    > git clone https://github.com/<your-github-username>/wrangler2
> cd wrangler2
    You can see that your fork is setup as the origin remote repository. Any changes you wish to make should be in a local branch that is then pushed to this origin remote. 
    > git remote -v
origin	https://github.com/<your-github-username>/wrangler2 (fetch)
origin	https://github.com/<your-github-username>/wrangler2 (push)
  • Add cloudflare/wrangler2 as the upstream remote repository. 
    > git remote add upstream https://github.com/cloudflare/wrangler2
> git remote -v
origin	https://github.com/<your-github-username>/wrangler2 (fetch)
origin	https://github.com/<your-github-username>/wrangler2 (push)
upstream	https://github.com/cloudflare/wrangler2 (fetch)
upstream	https://github.com/cloudflare/wrangler2 (push)
  • You should regularly pull from the main branch of the upstream repository to keep up to date with the latest changes to the project. 
    > git switch main
> git pull upstream main
From https://github.com/cloudflare/wrangler2
* branch            main       -> FETCH_HEAD
Already up to date.

Install dependencies

The Node.js dependencies of the project are managed by the npm tool.

This repository is setup as a mono-repo of workspaces. The workspaces are stored in the packages directory.

While each workspace has its own dependencies, you install the dependencies using npm at the root of the project.

  • Install all the dependencies 
    > cd wrangler2
> npm install

Do not run npm install in any of the workspaces directly.

Building and running

Each wrangler workspace in this project is written in TypeScript and compiled, by esbuild, into JavaScript bundles for distribution.

  • Run a distributable for a specific workspace (e.g. wrangler) 
    > npm start -w wrangler
  • Build a distributable for a specific workspace(e.g. wrangler) 
    > npm run build -w wrangler

Checking the code

The code in the repository is checked for type checking, formatting, linting and testing errors.

  • Run all checks in all the workspaces 
    > npm run check

When doing normal development you may want to run these checks individually.

Type Checking

The code is checked for type errors by TypeScript.

  • Type check all the code in the repository 
    > npm run check:type
  • VS Code will also run type-checking while editing source code, providing immediate feedback.

Linting

The code is checked for linting errors by ESLint.

  • Run the linting checks 
    > npm run check:lint
  • The repository has a recommended VS Code plugin to run ESLint checks while editing source code, providing immediate feedback.

Formatting

The code is checked for formatting errors by Prettier.

  • Run the formatting checks 
    > npm run check:format
  • The repository has a recommended VS Code plugin to run Prettier checks, and to automatically format using Prettier, while editing source code, providing immediate feedback.

Testing

Tests in a workspace are executed, by Jest, which is configured to automatically compile and bundle the TypeScript before running the tests.

  • Run the tests for all the workspaces 
    > npm run test
  • Run the tests for a specific workspace (e.g. wrangler) 
    > npm run test -w wrangler
  • Watch the files in a specific workspace (e.g. wrangler), and run the tests when anything changes 
    > npm run test-watch -w wrangler
    This will also run all the tests in a single process (rather than in parallel shards) and will increase the test-timeout to 50 seconds, which is helpful when debugging.

Steps For Making Changes

Every change you make should be stored in a git commit. Changes should be committed to a new local branch, which then gets pushed to your fork of the repository on GitHub.

  • Ensure your main branch is up to date 
    > git switch main
> git pull upstream main
  • Create a new branch, based off the main branch 
    > git checkout -b <new-branch-name> main
  • Stage files to include in a commit
    • Use VS Code
    • Or add and commit files via the command line
    > git add <paths-to-changes-files>
> git commit
  • Push changes to your fork 
    git push -u origin <new-branch-name>
  • Once you are happy with your changes, create a Pull Request on GitHub

Changesets

Every non-trivial change to the project - those that should appear in the changelog - must be captured in a "changeset". We use the changesets tool for creating changesets, publishing versions and updating the changelog.

  • Create a changeset for the current change. 
    > npx changeset
  • Select which workspaces are affected by the change and whether the version requires a major, minor or patch release.
  • Update the generated changeset with a description of the change.
  • Include the generate changeset in the current commit. 
    > git add ./changeset/*.md

Changeset message format

Each changeset is a file that describes the change being merged. This file is used to generate the changelog when the changes are released.

To help maintain consistency in the changelog, changesets should have the following format:

<TYPE>: <TITLE>

<BODY>

[BREAKING CHANGES <BREAKING_CHANGE_NOTES>]
  • TYPE should be a single word describing the "type" of the change. For example, one of feature, fix, refactor, docs or chore.
  • TITLE should be a single sentence containing an imperative description of the change.
  • BODY should be one or more paragraphs that go into more detail about the reason for the change and anything notable about the approach taken.
  • BREAKING_CHANGE_NOTES (optional) should be one or more paragraphs describing how this change breaks current usage and how to migrate to the new usage.

Changeset file example

The generated changeset file will contain the package name and type of change (eg. patch, minor, or major), followed by our changeset format described above.

Here's an example of a patch to the wrangler package, which provides a fix:

---
"wrangler": patch
---

fix: replace the word "deploy" with "publish" everywhere.

We should be consistent with the word that describes how we get a worker to the edge. The command is `publish`, so let's use that everywhere.

Types of changes (and deviation from semver)

We use the following guidelines to determine the kind of change for a PR:

  • Bugfixes and new features are considered to be 'patch' changes. If the new feature is experimental and its behaviour may functionally change, be sure to log warnings whenever they're used. (You'll note that this is where we deviate from semver, which otherwise suggests that behaviour/api changes should go into minor releases. We may revisit this in the future.)
  • New deprecation warnings for future breaking changes are considered as 'minor' changes. These changes shouldn't break existing code, but the deprecation warnings should suggest alternate solutions to not trigger the warning.
  • Breaking changes are considered to be 'major' changes. These are usually when deprecations take effect, or functional breaking behaviour is added with relevant logs (either as errors or warnings.)