Slate is an open-source project built for the Shopify Theme community and it needs contributions from the community to be truly successful. We encourage you to join us in our mission of enhancing the Shopify theme development experience!
The Slate Github repo exists for the theme development community to discuss and solve problems directly related to Slate. It is not the place to discuss general theme development problems, nor the place to seek help for non-Slate related problems.
Shopify Theme development is a big topic and it's completely normal that you will encounter problems which might require you to reach out for help. In fact, we provide several knowledge and support platforms for theme development:
If you encounter a bug, think of a useful feature, or find something confusing in the docs, please create a new issue!
We ❤️ pull requests. If you'd like to fix a bug, contribute to a feature or just correct a typo, please feel free to do so, as long as you follow our Code of Conduct.
If you're thinking of adding a big new feature, consider opening an issue first to discuss it to ensure it aligns to the direction of the project (and potentially save yourself some time!).
This repo is a monorepo consisting of multiple packages and is managed using Lerna.
To start working on the codebase:
git clone git@github.com:your-username/slate.git
Note: replace "your-username" with your GitHub handle
yarn bootstrap
This command will install project dependencies and make sure any references to Slate packages use the local versions of those packages instead of the version hosted on NPM. For example, in the package.json of @shopify/slate-tools, there is a dependency @shopify/slate-env. Instead of downloading @shopify/slate-env from NPM, we link to the copy found in the packages/slate-env folder.
yarn test
git commit -a -m="Your commit message"
git push origin master
See Github's official documentation for more details.
Create Slate Theme is typically run via yarn create slate-theme, however this command always pulls the latest version of create-slate-theme from NPM so you can't use it to test any changes you make locally.
To run your local version of create-slate-theme, do the following:
- In your terminal, navigate to the
packages/create-slate-themefolder in the Slate Repo - Run
node index.js <your-theme-name> [custom-theme]. The last two arguments are the same as when you would use when usingyarn create
In order to test changes you make to Slate Tools, you'll need to have a Slate theme project to test it with. To do this:
- See the Getting Started guide on how to get a Slate project up and running.
- In your terminal, go to
packages/slate-toolsdirectory in your forked version of the Slate repo (not in the node_modules folder of your theme project)
cd packages/slate-tools
- Create a link to your local Slate Tools project that has changes:
yarn link
- Now in your theme project, type the following to complete the link to your local Slate Tools project:
yarn link @shopify/slate-tools
That's it! Now when you run any Slate Tools commands, they should be run using your local version of Slate Tools and not the version downloaded from NPM.
If your change affects how people use the project (i.e. adding or removing functionality, changing the return value of a function, etc), please ensure the documentation website is also updated to reflect this.
The documentation website lives in the docs folder on the master branch and is hosted using GitHub Pages on the gh-pages branch.
You only need to update the source files and Travis CI will take care of deploying the changes when your Pull Request is merged into the master branch.
You can read both the README files in the v0 folder and the v1 folder to see how to run the documentation site locally.
The changelog is updated by the repo's maintainers since a personal access token with repository access is needed to handle GitHub's API call limits.
If this is your first time generating changelog entries, add your personal access token with public_repo privileges to the GITHUB_AUTH environment variable by adding the following to your .bashrc file:
# Lerna Changelog Personal Access Token for shopify/slate repo
export GITHUB_AUTH=your_personal_access_token
Note: replace "your_personal_access_token" with your GitHub personal access token
Run the changelog generator:
yarn changelog
If nothing appears, you may not have any PRs tagged with appropriate labels in this release or you may have already published those changes. If you just released v0.12.1 and the previous version was v0.12.0, run the following command to get the changes since v0.12.0:
yarn changelog -- --tag-from=v0.12.0
Copy the generated markdown from your terminal into CHANGELOG.md and add any additional comments you wish to include. If the title of the autogenerated changelog is Unreleased, make sure you change it the new version name.
Commit the changes directly to master branch, with a commit title of:
Changelog vX.X.X
Note: replace "X.X.X" with new repo version number
Finally, paste the updates you made to the changelog in the release tag notes, see example: v0.10.0 tag notes.
- Merge any changes you want to include in your next release into
master.
Note: If you are merging multiple PRs into master with a single PR (e.g. you are merging a working branch called v0.11.0 with multiple fixes made from multiple PRs into master), then do not squash and merge this PR because you will loose valuable details in the auto generated changelog
-
Update the CHANGELOG.md as described above
-
To select a new version number, and publish packages to NPM, run:
yarn run publish
Note: Make sure you are logged into your Shopify NPM account before publishing