diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 47b5c1f68..9440320c2 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -5,7 +5,7 @@ ### Checklist For contributors: -- [ ] I have [updated the docs](https://github.com/Shopify/slate/blob/master/CONTRIBUTING.md#documentation) to reflect these changes, if applicable. +- [ ] I have [updated the docs](https://github.com/Shopify/slate/blob/0.x/CONTRIBUTING.md#documentation) to reflect these changes, if applicable. For maintainers: - [ ] I have :tophat:'d these changes. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8ca1f99e5..8facb2a8e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,6 @@ # How to contribute -We ❤️ pull requests. If you'd like to fix a bug, contribute a feature or just correct a typo, please feel free to do so, as long as you follow our [Code of Conduct](https://github.com/Shopify/slate/blob/master/CODE_OF_CONDUCT.md). + +We ❤️ pull requests. If you'd like to fix a bug, contribute a feature or just correct a typo, please feel free to do so, as long as you follow our [Code of Conduct](https://github.com/Shopify/slate/blob/0.x/CODE_OF_CONDUCT.md). 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!). @@ -10,31 +11,37 @@ The `slate-theme` scaffolding is [intentionally barebones](https://shopify.githu ## Getting Started To start working on the codebase, first fork the repo, then clone it: + ``` git clone git@github.com:your-username/slate.git ``` -*Note: replace "your-username" with your GitHub handle* + +_Note: replace "your-username" with your GitHub handle_ Install all package dependencies and link local packages: + ``` npm run bootstrap ``` Write some features. Run the tests with: + ``` npm test ``` ## View changes to `slate-theme` package in a live store -Create a config.yml file with private app settings from your shop. See [config-sample.yml](https://github.com/Shopify/slate/blob/master/packages/slate-theme/config-sample.yml) as an example. +Create a config.yml file with private app settings from your shop. See [config-sample.yml](https://github.com/Shopify/slate/blob/0.x/packages/slate-theme/config-sample.yml) as an example. Go to the `slate-theme` package: + ``` cd packages/slate-theme ``` Deploy Slate to your shop and start testing your feature. + ``` slate deploy ``` @@ -42,6 +49,7 @@ slate deploy ## Folder Structure The following documents the folder structure for this project and what the purpose of each folder is: + ``` +-- docs/ ** API docs that live at https://shopify.github.io/slate +-- scripts/ ** Scripts used for development such as deployment and CI scripts @@ -60,15 +68,19 @@ reflect this. The docs live inside the `docs/` folder and are hosted at `https://shopify.github.io/slate`. To run the docs locally, first install the ruby dependencies: + ``` bundle install ``` -*If you are having troubles setting up jekyll, see https://jekyllrb.com/docs/installation/* + +_If you are having troubles setting up jekyll, see https://jekyllrb.com/docs/installation/_ Generate the docs: + ``` jekyll serve -s docs ``` + If you get a permission error, try `bundle exec jekyll serve -s docs` The documentation will then be visible at: @@ -79,47 +91,50 @@ The documentation will then be visible at: The changelog is updated by the repo's maintainers since a [personal access token](https://github.com/settings/tokens) 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* + +_Note: replace "your_personal_access_token" with your GitHub personal access token_ Run the changelog generator: + ``` npm run 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`: + ``` npm run changelog -- --tag-from=v0.12.0 ``` -Copy the generated markdown from your terminal into [CHANGELOG.md](https://github.com/Shopify/slate/blob/master/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. +Copy the generated markdown from your terminal into [CHANGELOG.md](https://github.com/Shopify/slate/blob/0.x/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](https://github.com/Shopify/slate/releases/tag/v0.10.0). +_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](https://github.com/Shopify/slate/releases/tag/v0.10.0). ## Publishing -1. Merge any changes you want to include in your next release into `master`. +1. 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_ -*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* +2. Update the [CHANGELOG.md](https://github.com/Shopify/slate/blob/0.x/CHANGELOG.md) as described above -2. Update the [CHANGELOG.md](https://github.com/Shopify/slate/blob/master/CHANGELOG.md) as described above +3. To select a new version number, publish packages to NPM, generate and deploy new `slate-theme` zips, run: -3. To select a new version number, publish packages to NPM, generate and deploy new `slate-theme` zips, run: ``` npm run publish ``` -*Note: Make sure you are logged into your Shopify NPM account before publishing* - - +_Note: Make sure you are logged into your Shopify NPM account before publishing_ diff --git a/README.md b/README.md index cb1326362..82dcae71e 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,14 @@ # Slate + [![CircleCI](https://circleci.com/gh/Shopify/slate.svg?style=svg&circle-token=f18ea06638792678e7dbfa1b8413570cd2896dff)](https://circleci.com/gh/Shopify/slate) -> ⓘ We're busy working on the next version of Slate which introduces a ton of cool new features to Shopify Theme development. Take a look in the [1.x branch](https://github.com/Shopify/slate/tree/1.x), give it a spin, and let us know what you think! +> **This branch is for Slate v0**. For the latest version of Slate, take a look in the [master branch](https://github.com/Shopify/slate). Slate is a theme scaffold and command line tool for developing Shopify themes. It is designed to assist your development workflow and speed up the process of developing, testing, and deploying themes to Shopify stores. It allows you to sync local files with your live shop, deploy to multiple environments at the same time, and organize stylesheets and scripts in a flexible way. ----------- +--- ## Documentation @@ -16,15 +17,15 @@ For full API documentation, go check out the [API docs](https://shopify.github.i ## Contributing For help on setting up the repo locally, building, testing, and contributing -please see [CONTRIBUTING.md](https://github.com/Shopify/slate/blob/master/CONTRIBUTING.md). +please see [CONTRIBUTING.md](https://github.com/Shopify/slate/blob/0.x/CONTRIBUTING.md). ## Code of Conduct All developers who wish to contribute through code or issues, take a look at the -[Code of Conduct](https://github.com/Shopify/slate/blob/master/CODE_OF_CONDUCT.md). +[Code of Conduct](https://github.com/Shopify/slate/blob/0.x/CODE_OF_CONDUCT.md). ## License -MIT, see [LICENSE](http://github.com/Shopify/slate/blob/master/LICENSE) for details. +MIT, see [LICENSE](http://github.com/Shopify/slate/blob/0.x/LICENSE) for details. diff --git a/packages/slate-cli/README.md b/packages/slate-cli/README.md index 97e4e99b9..86d479ad3 100644 --- a/packages/slate-cli/README.md +++ b/packages/slate-cli/README.md @@ -1,15 +1,16 @@ # Slate CLI -Slate is a command line tool for Shopify Theme development. It's designed to assist your development workflow +Slate is a command line tool for Shopify Theme development. It's designed to assist your development workflow and speed up the process of developing, testing and deploying themes to Shopify stores. ### Table of Contents -- [Installation](#installation) -- [Getting Started](#getting-started) -- [Updating Slate](#updating-slate) -- [Global Commands](#global-commands) -- [Theme Commands](#theme-commands) -- [License](#license) + +* [Installation](#installation) +* [Getting Started](#getting-started) +* [Updating Slate](#updating-slate) +* [Global Commands](#global-commands) +* [Theme Commands](#theme-commands) +* [License](#license) ## Installation @@ -26,23 +27,25 @@ You should now be able to run slate from your terminal. Try running `slate --ver ## Getting started #### 1. Create a new project + Run the following commands to create a new project: ```shell slate theme ``` -You will be prompted with some questions to help configure your theme. A new directory will be created within the +You will be prompted with some questions to help configure your theme. A new directory will be created within the current directory (similar to `git clone`). Once the boilerplate has been generated, Slate runs `npm install` to download remaining dependencies (~1min). #### 2. Configure your Store / Environment settings + When the theme generator has finished, the theme's `config.yml` file will open automatically. You will need to fill in the required fields for each store / environment. Comment out any environments that you want to set up later or Theme Kit will throw an error. > _For more details on configuring your environments please see our -**[Store configuration guide](https://github.com/Shopify/slate/blob/master/packages/slate-cli/store-configuration.md)**._ +> **[Store configuration guide](https://github.com/Shopify/slate/blob/0.x/packages/slate-cli/store-configuration.md)**._ #### 3. Navigating the codebase @@ -54,23 +57,24 @@ are the files that will be uploaded to your store. Some new folders have been included in the `/src` directory: -- `/icons` - custom svg icons. These are converted to snippets for use with `{% include %}` (see [slate#svg-icons](https://github.com/Shopify/slate#svg-icons)). -- `/scripts` - You can add sub-folders to help with organization. `scripts/theme.js` is the main entry point. -- `/scripts/vendor` - external JS. This folder is combined to a `vendor.js` file and included in the main layout. -- `/styles` - You can add sub-folders to help with organization. `styles/theme.scss` is the main entry point. +* `/icons` - custom svg icons. These are converted to snippets for use with `{% include %}` (see [slate#svg-icons](https://github.com/Shopify/slate#svg-icons)). +* `/scripts` - You can add sub-folders to help with organization. `scripts/theme.js` is the main entry point. +* `/scripts/vendor` - external JS. This folder is combined to a `vendor.js` file and included in the main layout. +* `/styles` - You can add sub-folders to help with organization. `styles/theme.scss` is the main entry point. #### 4. Start developing your Theme -You're ready to start developing with Slate. To get started, run the following command from your theme directory: - ```shell - slate start - ``` +You're ready to start developing with Slate. To get started, run the following command from your theme directory: + +```shell +slate start +``` - This will build your theme from the `/src` contents to the format required by Shopify (outputs a `/dist` directory). +This will build your theme from the `/src` contents to the format required by Shopify (outputs a `/dist` directory). - The `/dist` folder will be uploaded to the store / theme_id specified in your default environment. +The `/dist` folder will be uploaded to the store / theme_id specified in your default environment. - Slate will begin watching your theme directory for file changes and deploy them to your store whenever you make a change. +Slate will begin watching your theme directory for file changes and deploy them to your store whenever you make a change. ## Updating Slate @@ -80,14 +84,15 @@ npm install @shopify/slate --global ## Global commands -Command | Usage ---- | --- -[theme](#theme) | `slate theme [name] [--options]` -[migrate](#migrate) | `slate migrate [--options]` -[help](#help) | `slate -h` -[version](#version) | `slate -v` +| Command | Usage | +| ------------------- | -------------------------------- | +| [theme](#theme) | `slate theme [name] [--options]` | +| [migrate](#migrate) | `slate migrate [--options]` | +| [help](#help) | `slate -h` | +| [version](#version) | `slate -v` | ### theme + ``` slate theme [name] [--options] ``` @@ -95,25 +100,29 @@ slate theme [name] [--options] Generates a theme with build tools. The name argument is required and you will be prompted to enter it if it's not provided. #### options + ``` --yarn installs theme dependencies with yarn instead of npm ``` ### migrate + ``` slate migrate [--options] ``` -Converts an existing theme to work with Slate. Run this command from your project root to install dependencies and restructure your theme files into a `src/` directory. Empty `icons/`, `styles/` and `scripts/` folders will also be created. +Converts an existing theme to work with Slate. Run this command from your project root to install dependencies and restructure your theme files into a `src/` directory. Empty `icons/`, `styles/` and `scripts/` folders will also be created. Create `config.yml` in your root using [this sample file](https://github.com/Shopify/slate/blob//master/packages/slate-theme/config-sample.yml), then use [theme commands](#theme-commands) to start developing. #### options + ``` --yarn installs theme dependencies with yarn instead of npm ``` ### help + ``` slate [command] -h, slate [command] --help ``` @@ -121,6 +130,7 @@ slate [command] -h, slate [command] --help Outputs help information for Slate (`slate --help`) or a specific command (`slate deploy --help`). ### version + ``` slate -v, slate --version ``` @@ -129,16 +139,17 @@ Outputs the current version of Slate CLI installed on your system. ## Theme commands -Command | Usage ---- | --- -[build](#build) | `slate build` -[deploy](#deploy) | `slate deploy [--options]` -[start](#start) | `slate start [--options]` -[test](#test) | `state test` -[watch](#watch) | `slate watch [--options]` -[zip](#zip) | `slate zip` +| Command | Usage | +| ----------------- | -------------------------- | +| [build](#build) | `slate build` | +| [deploy](#deploy) | `slate deploy [--options]` | +| [start](#start) | `slate start [--options]` | +| [test](#test) | `state test` | +| [watch](#watch) | `slate watch [--options]` | +| [zip](#zip) | `slate zip` | ### build + ``` slate build ``` @@ -146,6 +157,7 @@ slate build Compiles your theme files and assets into a Shopify theme, found in the `dist` folder. No files will be uploaded to your shop. ### deploy + ``` slate deploy [--options] ``` @@ -155,18 +167,21 @@ Performs a fresh build followed by a full deploy; replacing existing files on th Running `slate deploy --manual` will instead create a new zip file of your theme (see [slate zip](#zip)) and open the admin themes page as defined by your environment where you can then manually install your theme from the zip file. #### options + ``` -e, --env deploy to a comma-separated list of environments -m, --manual disable auto-deployment of the theme files ``` Deploy to a different environment with the `-e` flag (short for `--env`) plus the environment name, or multiple environments at once with comma separated values + ``` slate deploy -e staging slate deploy -e development,staging,production ``` ### start + ``` slate start [--options] ``` @@ -174,11 +189,13 @@ slate start [--options] Performs a full deploy of your theme (see [slate deploy](#deploy)) and starts the watchers (see [slate watch](#watch)). #### options + ``` -e, --env deploy to a comma-separated list of environments ``` ### test + ``` slate test ``` @@ -186,6 +203,7 @@ slate test Uses the [@shopify/theme-lint](https://github.com/Shopify/theme-lint) package to run translation tests on your locales found in the `/src/locales` folder. The package checks for untranslated keys inside of your Liquid templates, missing translation keys in specific locale files, and translation key HTML validity. ### watch + ``` slate watch [--options] ``` @@ -193,11 +211,13 @@ slate watch [--options] Sets up the watchers for all theme assets and deploys the compiled versions to your shop. #### options + ``` -e, --env deploy to a specific environment ``` ### zip + ``` slate zip ``` diff --git a/packages/slate-cli/store-configuration.md b/packages/slate-cli/store-configuration.md index 08c11addf..a9f24f0e8 100644 --- a/packages/slate-cli/store-configuration.md +++ b/packages/slate-cli/store-configuration.md @@ -1,41 +1,41 @@ # Store / Environment Configuration Tips -Knowing what to put in your `config.yml` isn't always straightforward. This guide aims to clarify what data is needed, and where to get it. +Knowing what to put in your `config.yml` isn't always straightforward. This guide aims to clarify what data is needed, and where to get it. -_Note: [ThemeKit](http://shopify.github.io/themekit/) is the tool that powers Slate deploys. See it's +_Note: [ThemeKit](http://shopify.github.io/themekit/) is the tool that powers Slate deploys. See it's [configuration variables documentation](http://shopify.github.io/themekit/configuration/) for more details._ #### `config.yml` environment properties -- **store:** the shopify-specifc URL for this store/ environment (ie. [my-store.myshopify.com](https://my-store.myshopify.com)). -- **theme_id:** the unique id for the theme you want to write to when deploying to this store / environment -- **password:** the password generated via a private app on this store / environment (necessary for API access) +* **store:** the shopify-specifc URL for this store/ environment (ie. [my-store.myshopify.com](https://my-store.myshopify.com)). +* **theme_id:** the unique id for the theme you want to write to when deploying to this store / environment +* **password:** the password generated via a private app on this store / environment (necessary for API access) ### Finding your theme_id -_**warning:** some commands ([`start`](https://github.com/Shopify/slate/blob/master/packages/slate-cli#start), [`deploy`](https://github.com/Shopify/slate/blob/master/packages/slate-cli#deploy)) will overwrite the existing code on this `theme_id` with empty boilerplate. +_**warning:** some commands ([`start`](https://github.com/Shopify/slate/blob/0.x/packages/slate-cli#start), [`deploy`](https://github.com/Shopify/slate/blob/0.x/packages/slate-cli#deploy)) will overwrite the existing code on this `theme_id` with empty boilerplate. To avoid losing work, we suggest you go to [/admin/themes](https://my-store.myshopify.com/admin/themes) and duplicate an existing theme to work from._ Go to your store's [/admin/themes.xml](https://my-store.myshopify.com/admin/themes.xml), and copy the `id` for the theme you would like to update: - ![https://screenshot.click/17-02-w0fw2-zczky.png](https://screenshot.click/17-02-w0fw2-zczky.png) +![https://screenshot.click/17-02-w0fw2-zczky.png](https://screenshot.click/17-02-w0fw2-zczky.png) - ![https://screenshot.click/17-04-mng8o-k9da8.png](https://screenshot.click/17-04-mng8o-k9da8.png) +![https://screenshot.click/17-04-mng8o-k9da8.png](https://screenshot.click/17-04-mng8o-k9da8.png) - _alternatively, you can set the `theme_id` to **"live"** to update the published theme_ +_alternatively, you can set the `theme_id` to **"live"** to update the published theme_ ### Generating your password - Navigate to your store's private apps page ([/admin/apps/private](https://my-store.myshopify.com/admin/apps/private)). +Navigate to your store's private apps page ([/admin/apps/private](https://my-store.myshopify.com/admin/apps/private)). - ![https://screenshot.click/17-06-j9e9m-n2jxa.png](https://screenshot.click/17-06-j9e9m-n2jxa.png) +![https://screenshot.click/17-06-j9e9m-n2jxa.png](https://screenshot.click/17-06-j9e9m-n2jxa.png) - Create a new private app and copy the password: +Create a new private app and copy the password: - ![https://screenshot.click/17-07-u19kf-rx53b.png](https://screenshot.click/17-07-u19kf-rx53b.png) +![https://screenshot.click/17-07-u19kf-rx53b.png](https://screenshot.click/17-07-u19kf-rx53b.png) - Assign the private app permissions to "Read and Write" for theme templates and theme assets: +Assign the private app permissions to "Read and Write" for theme templates and theme assets: - ![https://screenshot.click/17-09-owv1p-5lugl.png](https://screenshot.click/17-09-owv1p-5lugl.png) +![https://screenshot.click/17-09-owv1p-5lugl.png](https://screenshot.click/17-09-owv1p-5lugl.png) diff --git a/packages/slate-theme/README.md b/packages/slate-theme/README.md index 02ec70945..a655c8acf 100644 --- a/packages/slate-theme/README.md +++ b/packages/slate-theme/README.md @@ -1,11 +1,12 @@ # Slate + [![CircleCI](https://circleci.com/gh/Shopify/slate.svg?style=svg&circle-token=f18ea06638792678e7dbfa1b8413570cd2896dff)](https://circleci.com/gh/Shopify/slate) Slate is a theme scaffold and command line tool for developing Shopify themes. It is designed to assist your development workflow and speed up the process of developing, testing, and deploying themes to Shopify stores. It allows you to sync local files with your live shop, deploy to multiple environments at the same time, and organize stylesheets and scripts in a flexible way. ----------- +--- ## Documentation @@ -14,15 +15,15 @@ For full API documentation, go check out the [API docs](https://shopify.github.i ## Contributing For help on setting up the repo locally, building, testing, and contributing -please see [CONTRIBUTING.md](https://github.com/Shopify/slate/blob/master/CONTRIBUTING.md). +please see [CONTRIBUTING.md](https://github.com/Shopify/slate/blob/0.x/CONTRIBUTING.md). ## Code of Conduct All developers who wish to contribute through code or issues, take a look at the -[Code of Conduct](https://github.com/Shopify/slate/blob/master/CODE_OF_CONDUCT.md). +[Code of Conduct](https://github.com/Shopify/slate/blob/0.x/CODE_OF_CONDUCT.md). ## License -MIT, see [LICENSE](http://github.com/Shopify/slate/blob/master/LICENSE) for details. +MIT, see [LICENSE](http://github.com/Shopify/slate/blob/0.x/LICENSE) for details. diff --git a/packages/slate-tools/README.md b/packages/slate-tools/README.md index 1775d4d4e..a310c0296 100644 --- a/packages/slate-tools/README.md +++ b/packages/slate-tools/README.md @@ -1,10 +1,11 @@ # @shopify/slate-tools -Tooling for Shopify themes using [Slate](https://github.com/Shopify/slate). +Tooling for Shopify themes using [Slate](https://github.com/Shopify/slate/tree/0.x). Best used in conjunction with the [Slate CLI](https://www.npmjs.com/package/@shopify/slate) package. ## Installation + ```bash $ npm install @shopify/slate-tools ``` @@ -14,15 +15,17 @@ $ npm install @shopify/slate-tools For full API documentation checkout the [API docs](https://shopify.github.io/slate/). ## Contributing + For help on setting up the repo locally, building, testing, and contributing -please see [CONTRIBUTING.md](https://github.com/Shopify/slate/blob/master/CONTRIBUTING.md). +please see [CONTRIBUTING.md](https://github.com/Shopify/slate/blob/0.x/CONTRIBUTING.md). ## Code of Conduct + All developers who wish to contribute through code or issues, take a look at the -[CODE_OF_CONDUCT.md](https://github.com/Shopify/slate/blob/master/CODE_OF_CONDUCT.md). +[CODE_OF_CONDUCT.md](https://github.com/Shopify/slate/blob/0.x/CODE_OF_CONDUCT.md). ## License -MIT, see [LICENSE.md](http://github.com/Shopify/slate/blob/master/LICENSE.md) for details. +MIT, see [LICENSE.md](http://github.com/Shopify/slate/blob/0.x/LICENSE.md) for details.