Skip to content
This repository has been archived by the owner on Oct 1, 2024. It is now read-only.

Latest commit

 

History

History
116 lines (68 loc) · 6.15 KB

CONTRIBUTING.md

File metadata and controls

116 lines (68 loc) · 6.15 KB

Quilt: a contributor's guide

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.

Ways to contribute

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.

Development

Getting Started

dev clone quilt
dev up

what is dev?

Getting productive

We 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:

🎩 in a local 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 tophat

In consuming repo:

yalc link --no-pure <package-name-in-package.json>  #yalc link --no-pure @shopify/react-server

You may also want to add .yalc and yalc.lock to .gitignore to remove some of the noise.

Emoji commits

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.

Documentation

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.

Testing

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

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.

Follow-up 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.

Feature branches

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.

Releasing

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.

External Contributors

Getting started

To start working on the codebase, first fork the repo, then clone it:

git clone [email protected]: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

What is dev?

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.