Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
197 lines (147 loc) · 8.94 KB

CONTRIBUTING.md

File metadata and controls

197 lines (147 loc) · 8.94 KB

Contributing to Razzle

Hi there! Thanks for your interest in Razzle. This guide will help you get started contributing.

Razzle is monorepo made up of a several npm packages powered by Lerna.

  • examples: All examples go in here.
  • packages: This is where the magic happens
    • babel-preset-razzle: Razzle's default Babel preset.
    • create-razzle-app: Razzle's CLI tool responsible for initialization of new projects
    • razzle: The core library
    • razzle-dev-utils: Utilities and helpers
  • scripts: Utility scripts related to cleaning and bootstrapping the repo
  • test: End-to-end tests

Developing locally

First, fork the repo to your GitHub account. Then clone your fork to your local machine and make a new branch for your feature/bug/patch etc. It's a good idea to not develop directly on master so you can get updates.

git clone https://github.com/<YOUR_GITHUB_USERNAME>/razzle.git
cd razzle
git checkout -B <my-branch>
NODE_ENV=development yarn install ---ignore-engines
# optionally install add-dependencies
sudo npm install add-dependencies -g

This will install all node_modules in all the packages and symlink inter-dependencies. Thus when you make local changes in any of the packages you can try them immediately in all the examples. add-dependencies can be used to just add packages to package.json.

Commands

  • yarn clean: Clean up all node_modules and remove all symlinks from packages and examples.
  • yarn test --runInBand: Runs all tests
  • yarn test:packages: Runs tests for packages
  • yarn test:e2e: Runs end-to-end tests
  • yarn build-docs: Builds docs/ updates doc TOC
  • yarn publish-all-canary: Does a razzle@canary release.
  • yarn publish-all-stable: Does a a stable release(uses the npm version released of the packages)
  • yarn new-example: Creates a new example from another example. yarn new-example basic new-example.
  • yarn bootstrap-examples: Run yarn with specific examples as workspaces. Automatically symlinks inter-dependent modules. Run yarn restrap in the example to reinstall.
  • yarn test:examples:simple: Runs tests for all simple examples (uses the npm version released of the packages)
  • yarn test:examples:complex: Runs tests for all complex examples (uses the npm version released of the packages)
  • yarn test:examples: Runs tests for all examples (uses the npm version released of the packages)

Workflow for working on razzle core with examples

git clone https://github.com/<YOUR_GITHUB_USERNAME>/razzle.git
cd razzle
git checkout -b my-feature-branch canary

# or
# git checkout -b my-feature-branch master
# git checkout -b my-feature-branch three

sudo npm install add-dependencies yalc -g

pwd
# /home/oyvind/Documents/GitHub/razzle/

NODE_ENV=development yarn install ---ignore-engines

# to make sure tests pass
yarn test --runInBand

# to add a new example
yarn new-example existingexample with-somefeature

# to work on a example
cd examples/basic
example="$(basename $PWD)"
pushd ../..

# if it is a example with webpack5 you need to do
yarn add -W webpack@5.24.0 html-webpack-plugin@5.2.0

# switch back to webpack4 later to work with webpack4
yarn add -W webpack@4.46.0 html-webpack-plugin@4.5.2

# then
yarn bootstrap-examples $example
popd
yarn build

# if you want to add dependencies to the example
add-dependencies somedependency
yarn restrap

# if you make changes to startserver plugin
pushd ../..
cd packages/razzle-start-server-webpack-plugin
yarn build
popd

# to run example tests with unreleased razzle packages with specific webpack and specific tests

WEBPACK_DEPS="webpack@5.24.0 html-webpack-plugin@5.2.0" PACKAGE_MANAGER="yalc" NPM_TAG="development" yarn test:examples --runInBand -t with-tailwindcss
WEBPACK_DEPS="webpack@4.46.0 html-webpack-plugin@4.5.2" PACKAGE_MANAGER="yalc" NPM_TAG="development" yarn test:examples --runInBand -t with-tailwindcss

# Commands being run during testing puts output and puppeteer screenshots in test-artifacts/
# Trouble with puppeteer?

sudo sysctl -w kernel.unprivileged_userns_clone=1

Updating your fork

When you want to pull down changes to your fork enter the following into your terminal:

git checkout master
git pull origin master

Adding examples

Use examples/basic as template

If you'd like to add an example, I suggest you duplicate the examples/basic folder yarn new-example basic your-exampleand use that as kind of base template. Before you start adding stuff, go ahead and change the name of the package in the your new example's package.json. Then go back to the project root and run yarn bootstrap-examples your-example. This will make sure that your new example is using your local version of all the packages.

Naming examples

All example folders should be named with-<thing-you-are-demonstrating>. Each example's npm package name (found in it's package.json) should look like razzle-examples-with-<thing-you-are-demonstrating>.

How to get your example merged

  • Make sure to comment the important parts of your code and include a well-written "Idea behind the example" section. This is more important to me than your actual code.
  • Keep your example limited to one idea / library / feature (e.g. don't submit with-styled-components-and-material-ui). That being said, there are times when this rule will be relaxed such as if you are showing how to use Apollo and Redux or <Flux Library> + React Router.
  • Your example MUST implement Hot Module Replacement. If it does not update when you make edits, you have broken something.
  • Your example should be minimalistic and concise, or a direct copy of another prominent example from the original library (like copying an example directly from react-redux).

Guidelines

Commit message guidelines

Why wasn't my PR merged?

I will do my best to write out my reasoning before closing a PR, but 80% of the time it falls under one of these...

  • You did not read this document
  • Your code breaks an internal application (I will be transparent about this)
  • Your code conflicts with some future plans (I will be transparent about this too)
  • You've said something inappropriate or have broken the Code of Conduct

Getting recognition

We use the project README to recognize the contributions of members of the project community.

To add a contributor: all-contributors add github_username doc,code

Valid contributing keys

Getting help

Tweet / DM @jaredpalmer Tweet / DM @nima_arf Tweet / DM @fivethreeo