Merge branch 'main' into xru/use-push-from-sm-api

prismicio · Jul 15, 2024 · 7d1946a · 7d1946a
2 parents 02ffa66 + ede0ef5
commit 7d1946a
Show file tree

Hide file tree

Showing 74 changed files with 1,877 additions and 984 deletions.
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
@@ -4,4 +4,4 @@
 # the repo. Unless a later match takes precedence,
 # @global-owner1 and @global-owner2 will be requested for
 # review when someone opens a pull request.
-*       @prismicio/devs
+*       @prismicio/dev-tools
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,56 +1,146 @@
-# Slice Machine Contributing Guide
+# Contributing
 
-Whether you're helping us fix bugs, improve the docs, or spread the word, we'd love to have you as part of the Prismic developer community!
+This package is primarily maintained by [Prismic](https://prismic.io)[^1]. External contributions are welcome. Ask for help by [opening an issue](https://github.com/prismicio/slice-machine/issues/new/choose), or request a review by opening a pull request.
 
-**Asking a question**: [Open a new topic][forum-question] on our community forum explaining what you want to achieve / your question. Our support team will get back to you shortly.
+## :gear: Setup
 
-**Reporting a bug**: [Open an issue][repo-bug-report] explaining your application's setup and the bug you're encountering.
+<!-- When applicable, list system requirements to work on the project. -->
 
-**Suggesting an improvement**: [Open an issue][repo-feature-request] explaining your improvement or feature so we can discuss and learn more.
+The following setup is required to work on this project:
 
-**Submitting code changes**: For small fixes, feel free to [open a PR][repo-pull-requests] with a description of your changes. For large changes, please first [open an issue][repo-feature-request] so we can discuss if and how the changes should be implemented.
+- Node.js
+- npm CLI
+- Yarn
 
-## Local development
+## :memo: Project-specific notes
 
-Clone the `slice-machine` repository to your local machine.
+<!-- Share information about the repository. -->
+<!-- What specific knowledge do contributors need? -->
 
-```
-git clone https://github.com/prismicio/slice-machine.git
-```
+> [!TIP]
+> Please update this section with helpful notes for contributors.
 
-Move into the folder, enable [Corepack](https://nodejs.org/dist/latest/docs/api/corepack.html) and install the dependencies.
+#### "SM" Types
 
-```
+- Slice Machine contains Slice Machine-specific versions of some `@prismicio/types-internal` types. For example, Slice Machine's `GroupSM` is a modified version of `@prismicio/types-internal`'s `Group`.
+- The "SM" types contain reshaped data that make it easy to perform Slice Machine-specific transformations. For example, `GroupSM` uses an array to define its fields while `Group` uses an object. The array makes it easy to change the order of fields.
+- "SM" types have `fromSM` and `toSM` helpers to convert one data type into the other.
+- The "SM" types will be removed at some point in the future to simplify cross-repository development.
+
+#### Tests
+
+##### Unit and integration with Vitest
+
+- `slice-machine-ui` contains unit and integration tests. The integration tests have been superseded by Playwright tests and will likely be removed in the future. Unit tests can be written as needed.
+- All other packages in the monorepo contain integration tests written using Vitest.
+
+##### End-to-end with Playwright
+
+See [playwright/README.md](./playwright/README.md) for details.
+
+#### Sentry
+
+- Sentry monitors errors in production.
+- Check Sentry regularly for errors. Especially check Sentry after publishing new package versions.
+
+## :construction_worker: Develop
+
+> [!NOTE]
+> It's highly recommended to discuss your changes with the Prismic team before starting by [opening an issue](https://github.com/prismicio/slice-machine/issues/new/choose).[^2]
+>
+> A short discussion can accelerate your work and ship it faster.
+
+```sh
+# Clone and prepare the project.
+git clone git@github.com:prismicio/slice-machine.git
 cd slice-machine
-corepack enable
-yarn
-```
+yarn install
 
-Start up the dev server.
+# Create a new branch for your changes (e.g. lh/fix-win32-paths).
+git checkout -b <your-initials>/<feature-or-fix-description>
 
+# Start the development watcher.
+# Run this command while you are working on your changes.
+yarn run dev
+
+# Build the project for production.
+# Run this command when you want to see the production version.
+yarn run build
+
+# Lint your changes before requesting a review. No errors are allowed.
+yarn run lint
+
+# Format your changes before requesting a review. No errors are allowed.
+yarn run prettier:check
+# Errors can be fixed automatically:
+yarn run prettier:fix
+
+# Test your changes before requesting a review.
+# All changes should be tested. No failing tests are allowed.
+yarn run test
 ```
-yarn dev
-```
 
-Now that the dev server is running you can start the Next.js project used for testing. Move into the `e2e-projects/next` folder and run the `slicemachine:dev` script.
+To start the development version of Slice Machine with a Prismic repository, use the `play` script.
+
+`yarn play` requires the `yarn dev` script to be running in the background.
+
+```sh
+# Start the most recent playground or create one if none exist.
+yarn play
+
+# Start an existing playground or create one if it doesn't exist.
+yarn play my-playground-name
+
+# Force create a new playground
+yarn play --new
+yarn play --new my-playground-name
+
+# Specify a framework (default: next)
+yarn play -f sveltekit
+yarn play --framework sveltekit
 
+# If `-f` is passed with a playground name and the playground
+# already exists, halt. If the playground does not exist, create
+# a new one with that framework.
+yarn play -f sveltekit my-playground-name
+
+# Don't start the project
+yarn play --no-start
+
+# Dry run
+yarn play -n
+yarn play --dry-run
 ```
-cd e2e-projects/next
-yarn slicemachine:dev
+
+## :building_construction: Submit a pull request
+
+> [!NOTE]
+> Code will be reviewed by the Prismic team before merging.[^3]
+>
+> Request a review by opening a pull request.
+
+```sh
+# Open a pull request. This example uses the GitHub CLI.
+gh pr create
+
+# Someone from the Prismic team will review your work. This review will at
+# least consider the PR's general direction, code style, and test coverage.
+
+# When ready, PRs should be merged using the "Squash and merge" option.
 ```
 
-Now you can go to your browser and open `localhost:9999` to see the Slice Machine app up and running with some demo slices and types.
-You're now ready to start working on your changes and see them updated in the app.
+## :rocket: Publish
 
-## E2E tests
+> [!CAUTION]
+> Publishing is restricted to the Prismic team.[^4]
 
-In order to contribute to Slice Machine you will need to maintain and write new e2e tests:
+Use the [**Publish stable**](https://github.com/prismicio/slice-machine/actions/workflows/publish-stable.yml) GitHub Action to publish a new version of Slice Machine and its child packages.
 
-- [Slice Machine e2e tests documentation](./playwright/README.md)
+Version increment types can be specified for each package using the action's workflow form. For example, you can choose to increment `slice-machine-ui` by a major, minor, or patch version. Select "decline" to skip incrementing the version.
 
-<!-- Links -->
+The GitHub Action is powered by a purpose-built script: `script/publish.ts`.
 
-[forum-question]: https://community.prismic.io
-[repo-bug-report]: https://github.com/prismicio/slice-machine/issues/new?assignees=&labels=bug&template=bug_report.md&title=
-[repo-feature-request]: https://github.com/prismicio/slice-machine/issues/new?assignees=&labels=enhancement&template=feature_request.md&title=
-[repo-pull-requests]: https://github.com/prismicio/slice-machine/pulls
+[^1]: This package is maintained by the DevTools team. Prismic employees can ask for help or a review in the [#team-dev-tools](https://prismic-team.slack.com/archives/CPG31MDL1) Slack channel.
+[^2]: Prismic employees are highly encouraged to discuss changes with the DevTools team in the [#team-dev-tools](https://prismic-team.slack.com/archives/CPG31MDL1) Slack channel before starting.
+[^3]: Code should be reviewed by the DevTools team before merging. Prismic employees can request a review in the [#team-dev-tools](https://prismic-team.slack.com/archives/CPG31MDL1) Slack channel.
+[^4]: Prismic employees can ask the DevTools team for [npm](https://www.npmjs.com) publish access.
diff --git a/README.md b/README.md
@@ -22,13 +22,16 @@ For the smoothest onboarding experience, go to [Prismic][prismic-dashboard], cre
 
 If you want to dive in without any guidance, follow these steps:
 
-Create a Next.js or Nuxt app:
+Create a Next.js, Nuxt, or SvelteKit app:
 ```
 npx create-next-app@latest my-app
 ```
 ```
 npx nuxi@latest init my-app
 ```
+```
+npm create svelte@latest my-app
+```
 
 Open the folder:
 ```
@@ -77,19 +80,19 @@ Whether you're helping us fix bugs, improve the docs, or spread the word, we'd l
 ## License
 
 ```
-   Copyright 2013-2021 Prismic <contact@prismic.io> (https://prismic.io)
+Copyright 2013-2024 Prismic <contact@prismic.io> (https://prismic.io)
 
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
 
-       http://www.apache.org/licenses/LICENSE-2.0
+    http://www.apache.org/licenses/LICENSE-2.0
 
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
 ```
 
 <!-- Links -->

diff --git a/package.json b/package.json
@@ -68,7 +68,7 @@
   "resolutions": {
     "connected-next-router/react-redux": "8.0.7",
     "react-beautiful-dnd/react-redux": "8.0.7",
-    "@prismicio/types-internal": "2.4.1"
+    "@prismicio/types-internal": "2.5.0"
   },
   "workspaces": [
     "e2e-projects/next",

diff --git a/packages/adapter-next/package.json b/packages/adapter-next/package.json
@@ -1,6 +1,6 @@
 {
 	"name": "@slicemachine/adapter-next",
-	"version": "0.3.40",
+	"version": "0.3.42",
 	"description": "Slice Machine adapter for Next.js.",
 	"keywords": [
 		"typescript",
@@ -67,7 +67,7 @@
 	},
 	"dependencies": {
 		"@prismicio/simulator": "^0.1.4",
-		"@prismicio/types-internal": "^2.4.1",
+		"@prismicio/types-internal": "^2.5.0",
 		"@slicemachine/plugin-kit": "workspace:*",
 		"common-tags": "^1.8.2",
 		"fp-ts": "^2.13.1",
@@ -76,8 +76,7 @@
 		"lz-string": "1.5.0",
 		"monocle-ts": "^2.3.13",
 		"newtype-ts": "^0.3.5",
-		"pascal-case": "^3.1.2",
-		"prismic-ts-codegen": "^0.1.17"
+		"pascal-case": "^3.1.2"
 	},
 	"devDependencies": {
 		"@prismicio/mock": "0.2.0",
@@ -96,6 +95,7 @@
 		"next": "14.1.3",
 		"prettier": "3.0.3",
 		"prettier-plugin-jsdoc": "1.1.1",
+		"prismic-ts-codegen": "^0.1.21",
 		"react": "18.2.0",
 		"rollup-plugin-preserve-directives": "0.2.0",
 		"size-limit": "8.2.4",