This guide is tailored to Shopifolk, although we welcome contributions from the broader development community as well.
Shopify has adopted a Code of Conduct that we expect Quilt contributors to adhere to. Please read the full text so that you can understand what actions will and will not be tolerated.
There are many ways to contribute to Quilt, some of which are:
- Filing bug reports
- Requesting new features or packages via an issue
- Bringing up areas for enhancement
- Hacking away on an issue from our backlog
- Improving tests or documentation
Want to contribute, but not sure how? Find us on Slack in #help-admin-web-platform.
dev clone quilt
dev upWe are adding documentation as we go in the Web Foundations repo. There you will find our decision records, principles, best practices and styleguides for writing and testing different kinds of components.
The documentation directory in this repo covers the more granular technical aspects of this project with a set of guides to help you get started developing with quilt. Of particular note for new folks are the following:
- Creating a new package is particularly aimed at developers just starting on the project.
- Getting started: some tools we recommend for getting the most out of this project.
You can use yalc to publish the package and nodemon to watch the file changes.
This had been added as a tophat script to allow for faster iteration.
In quilt:
PKG_NAME=<package-folder-name> yarn tophat #PKG_NAME=react-server yarn tophatIn consuming repo:
yalc link --no-pure <package-name-in-package.json> #yalc link --no-pure @shopify/react-serverYou may also want to add .yalc and yalc.lock to .gitignore to remove some of the noise.
We have found that prefacing a commit message or PR title with an emoji can be a great way to improve the developer experience when browsing the repo code. Additionally, it is a terse way to convey information. Many of our contributors have found the guide at https://gitmoji.carloscuesta.me/ to be helpful in preserving this dynamic.
If your change affects the public API of any packages within Quilt (i.e. adding or
changing arguments to a function, adding a new function, changing the
return value, etc), please ensure the documentation is also updated to
reflect this. Documentation is in the README.md files of each package. If further documentation is needed please communicate via Github Issues.
The packages in Quilt are used in mission-critical production scenarios. As such, we try not to merge any untested code. The coverage doesn't strictly need to be 100% across the board, but testing should remain a primary concern.
To run the full test suite, simply run dev test. In order for tests to run properly, you may need to first run dev build
TODO comments may seem like a great placeholder for work in progress. We prefer to handle this in a different way, using a combination of feature branches and github issues.
If your changes are complete in functionality, but you're not quite happy with auxillary things like documentation or testing, then feel free to make a github issue to track the work that needs to be done. These issues should be linked in the PRs that need a bit more work. This will allow context to be drawn from the code in a more trackable way than a TODO comment. Also, it allows the PR reviewers to see that the documentation or testing is purposefully incomplete and that an appropriate issue exists to track the follow-up work.
Another option, if you'd like to break work down into reviewable chunks, is to use a feature branch. This would be an initially empty branch that contains the entirety of your feature. Additional units of work can be distributed across several PRs into the feature branch, merged independently, and then the feature branch can be merged as a complete unit into the main branch, when it's ready.
The release process currently involves some manual steps to complete. Please drop a notice in the #help-admin-web-platform Slack channel when you're ready to merge a new PR into main, and we will orchestrate a new release. The repo owner can follow this guide to create a release.
Note Version numbers in package.json files and CHANGELOG.md files should never be altered manually. This will be done via scripts as part of the release process.
To start working on the codebase, first fork the repo, then clone it:
git clone git@github.com:your-username/quilt.git
Note: replace "your-username" with your Github handle
Install the project's dependencies (make sure you first have yarn installed):
yarn
dev is a tool to standardize a small set of common tasks across all projects at Shopify. If you're wondering how to execute the dev <cmd> commands as an external contributor, you can see where they are defined in this project's dev.yml file, which is pretty self-explanatory.