Merge branch 'main' into preview-url-update

chapter-three · Feb 14, 2024 · 9f506ca · 9f506ca
2 parents 765b2f2 + f73c064
commit 9f506ca
Show file tree

Hide file tree

Showing 95 changed files with 5,056 additions and 3,678 deletions.
diff --git a/.eslintignore b/.eslintignore
@@ -4,3 +4,4 @@ public
 node_modules
 *.esm.js
 /drupal
+/drupal-*
diff --git a/.github/workflows/next-drupal.yml b/.github/workflows/next-drupal.yml
@@ -1,5 +1,8 @@
 name: next-drupal
 on:
+  push:
+    branches:
+      - main
   pull_request_target:
     types: [opened, reopened, synchronize]
 

diff --git a/.gitignore b/.gitignore
@@ -1,97 +1,44 @@
-# Logs
-logs
-*.log
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-lerna-debug.log*
-
-# Runtime data
-pids
-*.pid
-*.seed
-*.pid.lock
-
-# Directory for instrumented libs generated by jscoverage/JSCover
-lib-cov
-
-# Coverage directory used by tools like istanbul
-coverage
-
-# nyc test coverage
-.nyc_output
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
 
-# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
-.grunt
-
-# Bower dependency directory (https://bower.io/)
-bower_components
-
-# node-waf configuration
-.lock-wscript
-
-# Compiled binary addons (http://nodejs.org/api/addons.html)
-build/Release
-
-# Dependency directories
+# dependencies
 node_modules/
-jspm_packages/
-
-# Typescript v1 declaration files
-typings/
-
-# Optional npm cache directory
-.npm
-
-# Optional eslint cache
-.eslintcache
-
-# Optional REPL history
-.node_repl_history
-
-# Output of 'npm pack'
-*.tgz
-
-# dotenv environment variables file
-.env
-
-# gatsby files
-.cache/
-
-# Mac files
-.DS_Store
-
-# Yarn
-yarn-error.log
+package-lock.json
 .pnp/
 .pnp.js
-# Yarn Integrity file
-.yarn-integrity
-.yarn
+.yarn/install-state.gz
 
-.netlify/
+# build/test artifacts
+/.eslintcache
+/packages/*/.turbo
+/packages/*/coverage
+/packages/*/dist
 
-# Editors
-.vscode/*
-!.vscode/tasks.json
-!.vscode/launch.json
-!.vscode/extensions.json
+# output of 'npm pack'
+/packages/*/*.tgz
 
-# phpstorm editor
-.idea/
+# misc
+.DS_Store
+*.pem
 
-# NPM lock files
-package-lock.json
+# IDE files
+/.idea
+/.vscode
+!/.vscode/tasks.json
+!/.vscode/launch.json
+!/.vscode/extensions.json
+
+# debug
+lerna-debug.log*
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
 
-# Cypress
-examples/**/cypress/screenshots
-examples/**/cypress/videos
+# environment variables file
+.env
+.envrc
 
-# Other
-*__clone*
-dist
-examples/certificates/*
-drupal/web/sites/default/settings.local.php
-.next
-drupal/web/phpunit.xml
-keys
+# more misc
+/*__clone__
+/drupal/web/phpunit.xml
+/drupal/web/sites/default/settings.local.php
+/drupal-*
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -157,7 +157,7 @@ For example:
 
 The `<scope>` can be empty (e.g. if the change is a global or difficult to assign to a single component), in which case the parentheses are omitted and the first line just becomes: `<type>: <subject>`
 
-The `<!>` is optional. It must be used for a BREAKING CHANGE. For example, `fix(widgets)!: Fix incompatibility with widget v2` indicates the bugfix required a breaking change.
+The `<!>` is optional. It should be used for a BREAKING CHANGE. For example, `fix(widgets)!: Fix incompatibility with widget v2` indicates the bugfix required a breaking change. Note that the "BREAKING CHANGE:" FOOTER is REQUIRED (see below).
 
 ### Commit message `<body>`
 

diff --git a/MAINTAINING.md b/MAINTAINING.md
@@ -0,0 +1,213 @@
+# Maintenance guide
+
+This document is for maintainers to explain the various procedures for all the projects in this monorepo.
+
+## Making releases
+
+### `next` (Drupal Module)
+
+While maintaining releases for packages, starters and examples is done with Lerna, releases for Drupal modules are controlled by drupal.org’s infrastructure, so these steps don’t involve Lerna.
+
+1. Optionally, create a new branch on drupal.org.
+
+   1. Follow the “Release branches” rules described on the [“Release naming conventions” documentation](https://www.drupal.org/docs/develop/git/git-for-drupal-project-maintainers/release-naming-conventions).
+   2. On Drupal.org’s GitLab, [create a new branch](https://git.drupalcode.org/project/next/-/tags/new).
+   3. In the monorepo’s `package.json`, update the `sync:modules` script to use the new branch name. The monorepo’s `main` branch will then sync with this new drupal.org branch.
+
+      For example, change:
+
+      ```
+      "sync:modules": "./scripts/sync-repo.sh 2.x [email protected]:project/ \"modules/*\"",
+      ```
+
+      to:
+
+      ```
+      "sync:modules": "./scripts/sync-repo.sh 3.x [email protected]:project/ \"modules/*\"",
+      ```
+
+2. Run `yarn sync:modules` to sync the latest commit on `main` with the git repo on drupal.org. All recent changes will be squashed into a commit using the latest commit message.
+
+3. On Drupal.org’s GitLab, [tag a release](https://git.drupalcode.org/project/next/-/tags/new) following the [“Release tags naming conventions” docs](https://www.drupal.org/docs/develop/git/git-for-drupal-project-maintainers/release-naming-conventions#release-tags).
+
+4. On Drupal.org’s Next.js project page, [create a release](https://www.drupal.org/node/add/project-release/3192303) using the git tag you just created.
+
+### `next-drupal` (NPM package)
+
+Since we are using semantic commits, Lerna is able to read the git commits since the last release to auto-generate a CHANGELOG and to determine if the next release should be a:
+
+- major version bump (e.g. 1.0.0 to 2.0.0). This will happen when Lerna finds a `BREAKING CHANGE` commit message.
+- minor version bump (e.g. 1.0.0 to 1.1.0). This will happen when Lerna finds a `feat` commit message.
+- patch version bump (e.g. 1.0.0 to 1.0.1). This is the default version bump for bug fixes, etc.
+- prerelease version bump (e.g. 1.0.0-alpha.0 to 1.0.0-alpha.1)
+
+We’ll be using Lerna’s `--no-push` flag so that Lerna does not push git tags and commits automatically. This allows us to delete any commits and tags locally if we make a mistake.
+
+1. **Tag a new release**
+
+   - **to make the next logical semantic version**, run:
+
+     ```
+     npx lerna version --no-push
+     ```
+
+   - **to make a new alpha prerelease version:**
+
+     If the current version is not a prerelease version, you’ll need to explicitly tell Lerna that the next version should be an alpha release with:
+
+     ```
+     npx lerna version --conventional-prerelease --no-push
+     ```
+
+     When creating a new prerelease version of `next-drupal`, Lerna will automatically determine if it needs to be a `premajor` (2.0.0-alpha.0), `preminor` (1.1.0-alpha.0), or `prepatch` (1.0.1-alpha.0) version.
+
+   - **to make a new beta prerelease version:**
+
+     If the current version is not a beta version, you’ll need to explicitly tell Lerna that the next version should be a beta release with:
+
+     ```
+     npx lerna version --conventional-prerelease --preid beta --no-push
+     ```
+
+   - **to make a new regular version from a prerelease version:**
+
+     If the current version is a prerelease version, you’ll need to explicitly tell Lerna that the next version should no longer be a prerelease version with:
+
+     ```
+     npx lerna version --conventional-graduate --no-push
+     ```
+
+   **Confirm changes**
+
+   When Lerna asks “Are you sure you want to create these versions?”, carefully check if the versions listed are the ones you expect.
+
+2. **Push git changes** with:
+
+   ```
+   git push
+   git push --tags
+   ```
+
+3. **Publish the release**
+
+   Ensure you have authenticated with npmjs.com using `npm login`.
+
+   Then, while your local git working area is clean of changes and `HEAD` is pointing to the commit created in step 1, have Lerna build, prepare, package and publish your release.
+
+   For a new prerelease version, specify the `canary` dist-tag with:
+
+   ```
+   npx lerna publish --dist-tag canary from-git
+   ```
+
+   Otherwise, use:
+
+   ```
+   npx lerna publish from-git
+   ```
+
+   Maintainers will need permission to publish to `next-drupal` on npmjs.com. http://npmjs.com/package/next-drupal
+
+4. **Confirm the release**
+
+   Look at the “Current Tags” section of [next-drupal’s npmjs page](https://www.npmjs.com/package/next-drupal?activeTab=versions) and confirm that the newest release is listed and that the `latest` tag and the `canary` tag point at the expected versions.
+
+For more information, see Lerna’s [version docs](https://github.com/lerna/lerna/tree/main/libs/commands/version) and [publish docs](https://github.com/lerna/lerna/tree/main/libs/commands/publish).
+
+### Examples
+
+The code in the examples repos do not strictly require a versioned release since they simply contain an example usage of the latest `next-drupal` release. However, each example has its own separate git repo so developers can see previous versions of the latest example.
+
+1. Optionally, **create a tag** that is Lerna-compatible matching the format: `[project]@[version]`, e.g. `[email protected]`
+
+   ```
+   git tag [email protected]
+   git push --tags
+   ```
+
+2. **Sync git repositories** with:
+
+   ```
+   yarn sync:examples
+   ```
+
+   All recent changes on `main` will be squashed into a commit on the target git repo using the latest commit message.
+
+### Starters
+
+1. **Update package.json** with the new release version for that starter, e.g. `2.0.0-alpha.0`. This is important so the developer knows which version of the starter they had when they first started their project.
+
+2. **Create a tag** that is Lerna-compatible matching the format: `[project]@[version]`, e.g. `[email protected]`
+
+   ```
+   git tag [email protected]
+   git push --tags
+   ```
+
+3. **Sync git repositories**
+
+   If the release is a prerelease, sync the monorepo with:
+
+   ```
+   yarn sync:starters
+   ```
+
+   If the release is not a prerelease, sync the monorepo with:
+
+   ```
+   yarn sync:starters:release
+   ```
+
+   All recent changes on `main` will be squashed into a commit on the target git repo using the latest commit message.
+
+4. **Create a GitHub release and tag**
+
+   The git tag created in step 1 was for the monorepo; it doesn’t exist in the starters’ git repos. We’ll create a GitHub release to make it easier for developers to see the changes between different versions of the starter.
+
+   To create a GitHub release, go to the releases page for:
+
+   - [basic-starter](https://github.com/chapter-three/next-drupal-basic-starter/releases)
+   - [graphql-starter](https://github.com/chapter-three/next-drupal-graphql-starter/releases)
+
+   And then:
+
+   1. Click the “Draft a new release” button.
+   2. In the **“Target:” drop-down**, select the `main` branch if this is going to be a normal release or select the `canary` branch if this is going to be a prerelease.
+   3. In the **“Choose a tag” widget**, type the new git tag, e.g. `2.0.0-alpha.0`, and hit `enter`. The help text will say “Excellent! This tag will be created from the target when you publish this release.”
+   4. In the “Release title” text field, type the same tag as the previous step.
+   5. Check either the “Set as a pre-release” checkbox or the “Set as the latest release” checkbox.
+   6. Click the “Publish release” button.
+
+### Docs
+
+@TODO: Expand details the next time docs are deployed.
+
+Documentation is deployed to Vercel and controlled via the following Git branches:
+
+- `v1.6`
+- `v1`
+- `v0`
+
+## Tests
+
+The Jest tests currently rely on a Drupal 9.4 installation deployed to [tests.next-drupal.org](https://tests.next-drupal.org) on Pantheon.
+
+Developers will need a copy of the db, a copy of the installation files, and to set the following environment variables when running tests locally:
+
+```dotenv
+export DRUPAL_BASE_URL='https://tests.next-drupal.org'
+export DRUPAL_CLIENT_ID='example-xxxx'
+export DRUPAL_CLIENT_SECRET='example-xxxx'
+export DRUPAL_USERNAME='Umami'
+export DRUPAL_PASSWORD='example-xxxx'
+```
+
+The files, db and environment variable values can be obtained from other Chapter Three developers.
+
+@TODO: Replace the live server with a way to install Drupal with the needed demo content and config. The updated docs should not be here, but instead in CONTRIBUTING.md.
+
+## Drupal (`/drupal` directory)
+
+This is probably a single Drupal install with the config for all the examples and is used for running Cypress tests.
+
+@TODO Confirm speculation by getting a copy of the database so `/drupal` can be run locally.
diff --git a/drupal/.gitignore b/drupal/.gitignore
@@ -29,3 +29,6 @@
 /oauth-keys/*.key
 /web/sites/default/settings.local.php
 /web/sites/default/services.local.yml
+
+# build/test artifacts
+/.turbo