Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update docs #143

Merged
merged 1 commit into from
Apr 2, 2024
+317 −316
Merged

Update docs #143

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 7 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,8 +25,9 @@ Or if your theme has a `package.json`:
npm add --save-dev @thebeyondgroup/shopkeeper
```
> :rotating_light: It is not currently possible to use Shopkeeper as a plugin
> to the homebrew installation of the Shopify CLI. To use it, you need to
> install it as a global npm package and use the `shopkeeper` executable.
> to the homebrew installation of the Shopify CLI. To use it alongside this
> version of the CLI, you need to install it as a global npm package and use
> the `shopkeeper` executable.
### tl;dr

Expand All @@ -48,8 +49,8 @@ To deploy _directly_ to the live theme after pulling down the live theme's setti
shopkeeper theme deploy --strategy basic
```

For a more complete introduction and walkthrough of how to use Shopkeeper, see
[guide](/docs/the_complete_guide.md).
Read [The Complete Guide](/docs/the_complete_guide.md) for an introduction and
walkthrough of how to use Shopkeeper.

## Commands

Expand Down Expand Up @@ -83,7 +84,7 @@ It uses a `.shopkeeper` folder at the root of your project to store buckets of s
>
> Therefore, we call our groups of settings buckets. :bucket:
In multi-store, multi-region setups, you might have a directory for
In multi-store, multi-region setups, you might have a bucket for
each region. Say `canada`, `united-states`, or `united-kingdom`. Or you might
use a bucket to contains the settings for an A/B test.

Expand Down Expand Up @@ -124,7 +125,7 @@ installation of [Dawn](https://github.com/shopify/dawn):
└── .current-bucket
```

Each folder contains theme settings stored in their corresponding `config`,
Each bucket contains theme settings stored in their corresponding `config`,
`sections`, and `templates` folders. It also contains a `.env` file that's
copied to the project root as `.env ` when the bucket is switched.

Expand Down
44 changes: 22 additions & 22 deletions docs/the_complete_guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,20 +10,20 @@ expects a single usage of a theme to be represented by a single repo. It will
automatically open PRs as customizations are made and there is no way to
separate a theme's data from its files.

We want to use a single theme and repo for all three expansion stores to
reduce development effort. We only want a store's settings to differ. We also
want a development workflow that parallels something you might use when doing
custom full-stack web development. We want to open PRs for changes, have
preview environments created and updated automatically with each commit pushed,
and for preview environments to be cleaned up once PRs are merged.
We want to use a single theme and repo for all three expansion stores to reduce
development effort. We only want a store's settings to differ. We also want a
development workflow that parallels something you might use when doing custom
full-stack web development. We want to open PRs for changes, have preview
environments created and updated automatically with each commit pushed, and for
preview environments to be cleaned up once PRs are merged.

The [Shopify CLI](https://shopify.dev/docs/themes/tools/cli/) provides a
wonderful set of primitive commands to interact with a single store and a
single theme. With this foundation, we can build a workflow and more
sophisticated commands to solve the problem we have just described.

We decided to use GitHub Actions for CI/CD and to build Shopkeeper to encapsulate
the common operations the workflow above would require.
We decided to use GitHub Actions for CI/CD and to build Shopkeeper to
encapsulate the common operations the workflow above would require.

The first step to build this workflow is to establish a way to manage theme
settings. Theme settings are important because they are the data that defines
Expand Down Expand Up @@ -191,10 +191,10 @@ Shopkeeper supports multiple deployment strategies:

By default, Shopkeeper assumes you want to use a [blue/green deployment
strategy](https://en.wikipedia.org/wiki/Blue–green_deployment). A blue/green
deployment strategy in the context of Shopify theme development
means alternating between a blue and a green theme. One theme is live and the
other we refer to as on-deck. For example, using this approach, if the blue
:large_blue_circle: theme is live, the green :green_circle: theme is on-deck.
deployment strategy in the context of Shopify theme development means
alternating between a blue and a green theme. One theme is live and the other
we refer to as on-deck. For example, using this approach, if the blue :large_blue_circle:
theme is live, the green :green_circle: theme is on-deck.
When updates are to be made to a storefront, the on-deck receives the changes
and when it is ready, it is published.

Expand Down Expand Up @@ -474,16 +474,16 @@ jobs:
**Preview:** [Storefront](https://${{ vars.SHOPIFY_FLAG_STORE }}?preview_theme_id=${{ env.THEME_ID }}) | [Admin](https://${{ vars.SHOPIFY_FLAG_STORE }}/admin/themes/${{ env.THEME_ID }}/editor)
delete_prev_regex_msg: "Preview:" # OPTIONAL
```
To generate a preview theme, we listen to pushes on any branch other than `main`
and ones starting with `github-action/`. Branches starting with `github-action/`
are used for settings commits. We restore the theme settings from our
`production` bucket, build the theme, and push it to Shopify.

> :warning: We use a special `theme create` command that's provided by Shopkeeper that ensures theme
> creation is idempotent. You can't guarantee the order your workflows will run,
> so we need to make sure that an update is created no matter if it already
> exists.`theme push --unpublished` is not idempotent and will add many themes of
> the same name, so it cannot be used.
To generate a preview theme, we listen to pushes on any branch other than
`main` and ones starting with `github-action/`. Branches starting with
`github-action/` are used for settings commits. We restore the theme settings
from our `production` bucket, build the theme, and push it to Shopify.

> :warning: We use a special `theme create` command that's provided by
> Shopkeeper that ensures theme creation is idempotent. You can't guarantee the
> order your workflows will run, so we need to make sure that an update is
> created no matter if it already exists.`theme push --unpublished` is not
> idempotent and will add many themes of the same name, so it cannot be used.

When a PR is opened, we generate a comment on the PR with a link to the preview
theme on Shopify.
Expand Down
Loading