👋 We're so excited you're interested in helping with Blitz! We happy to help you get started, even if you don't have any previous open-source experience :)
First Things First
- New to open source? take a look at How to Contribute to an Open Source Project on GitHub
- Familiarize yourself with the Blitz Code of Conduct
- Learn how the community operates
Video Overview of Our Codebase
If you want,watch this video for a walkthrough of the entire Blitz codebase. This is a great way to get an overview of the various parts and how they fit together!
What to Work On?
Issues with the label
status/ready-to-work-onare the best place to start.
If you find one that looks interesting and no one else is already working on it, comment in the issue that you are going to work on it. But only claim an issue if you can start work on it within a couple days.
Please ask as many questions as you need, either directly in the issue or in Slack. We're happy to help!
The Blitzjs.com website and documentation repo also has issues with
ready to work on | help wanted.
Things that are ALWAYS welcome
- Adding tests
- Improved documentation
- Improved error messages
- Improved logging (i.e. more clear, more beautiful)
- Performance or security improvements
- Educational content like blogs, videos, courses
If there's some other way you'd like to contribute, ask us about it in Slack!
After you contribute in any way, please add yourself as a contributor via the@all-contributors bot!
Our Codebase is a Garden
The Blitz codebase is like a community garden. There's a lot of beautiful plants and vegetables, but it won't take long until you find some weeds! When you find weeds, please remove them :) Minor refactoring is always encouraged. If you'd like to do some major refactoring, it's best to first either open an issue or check with us in Slack. Most likely we'll agree with you.
What to Expect After Submitting a PR
A Blitz maintainer will review your PR, usually within a couple days.
If your PR changes user facing code, make sure you also made a PR to the docs repo, otherwise this will block your PR from being merged.
You also need to add tests to cover the changes you made.
Once all the requirements are met and the maintainer is happy with your code, they will merge it to the canary branch. It will then be included in the next Blitz release.
Lastly, you will be added the all-contributors list as an official Blitz contributor. Congratulations!!
We use aGitHub Project Board to track all issues and PRs.
We give liberal commit access to the Blitz repo to anyone who is a half-way regular contributor. This allows you to push branches directly to the Blitz repo without using a fork.
We'll often give someone access if we notice they are regularly contributing. But you're also welcome to ask for access if you are regularly helping but haven't been given access yet.
In the main Blitz repo, code reviews by code owners are required to merge PRs.
But in the docs repo, anyone can merge PRs once someone else has approved the PR.
1. Forkthe blitz repo
2. Clone your forked repo
# replace USERNAME below with your GitHub usernamegit clone firstname.lastname@example.org:USERNAME/blitz.gitcd blitz
3. Install dependencies
4. Start the package server. This must be running for any package development or example development
5. Run tests
Testing Development Version of Blitz
Currently, to test the local dev version of Blitz, you can only test an app inside the
blitz/examples/folder. In there, the blitz dependency will automatically use the local dev version. We mainly use the
storeexample apps. We use them for development testing and for blitz integration tests. You must also make sure you are running
yarn devin the
blitzfolder at the same time.
For using in apps outside the repo,yalc should work, but hasn't been tested yet. If you figure out how to use yalc, please make a PR to this page explaining how to set it up!
Sync your fork
git remote add upstream email@example.com:blitz-js/blitz.git./scripts/fetchRemote.shgit merge upstream/canary
Link the Blitz CLI (Optional)
The following will link the development CLI as a local binary so you can use it anywhere for testing.
yarn link-cli// `yarn unlink-cli` will unlink
Develop a Blitz
1. Change to a package directory
2. Start the test runner
Develop a Blitz
1. Change to an example directory
2. Follow instructions in the example's README
If you run into issues that should be documented here, please submit a PR! ❤️
Windows Subsystem for Linux
node-ptyerror when running
yarn. Fix by installing
sudo apt install -y make python build-essential
Yarn policies error
This issue is related with yarn > 1.19.1, if you get an error like this in your console:
An unexpected error occurred: "expected workspace package to exist for \"@wessberg/rollup-plugin-ts\"
Fix it with this command:
yarn policies set-version 1.19.1