From 83562b8b2dcab78d1ee82a931090cb388d49ef5f Mon Sep 17 00:00:00 2001 From: Lennart Date: Thu, 9 Nov 2023 10:15:29 +0100 Subject: [PATCH] chore: Add Deploy preview to docs & improve workflow (#2092) * chore(repo): Improve docs * chore(repo): Fix some bugs in preview workflow --- .github/workflows/preview.yml | 14 +++++++------- docs/CICD.md | 6 +++--- docs/CONTRIBUTING.md | 2 +- docs/PUBLISH.md | 24 +++++++++++++++--------- 4 files changed, 26 insertions(+), 20 deletions(-) diff --git a/.github/workflows/preview.yml b/.github/workflows/preview.yml index b2ad68a5b4..79ec8ba99b 100644 --- a/.github/workflows/preview.yml +++ b/.github/workflows/preview.yml @@ -94,8 +94,8 @@ jobs: - name: Create preview comment - Deploying uses: marocchino/sticky-pull-request-comment@v2.8.0 with: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - number: ${{ github.event.pull_request.number }} + GITHUB_TOKEN: ${{ secrets.CLERK_COOKIE_PAT }} + number: ${{ github.event.issue.number }} header: ${{ env.COMMENT_HEADER}} message: | Hey @${{ github.event.comment.user.login }}, your preview is currently deploying and should be available shortly. @@ -112,14 +112,14 @@ jobs: id: vercel-wait-for-deploy run: | vercel inspect --token=${{ secrets.VERCEL_CLERK_COOKIE_TOKEN }} --wait ${{ steps.vercel-deploy.outputs.url }} --timeout 10m --scope clerk-production - vercel alias set ${{ steps.vercel-deploy.outputs.url }} javascript-preview-${{ github.event.pull_request.number }}.clerkpreview.com --token=${{ secrets.VERCEL_CLERK_COOKIE_TOKEN }} --scope clerk-production - echo "stable_url=https://javascript-preview-${{ github.event.pull_request.number }}.clerkpreview.com" >> $GITHUB_OUTPUT + vercel alias set ${{ steps.vercel-deploy.outputs.url }} javascript-preview-${{ github.event.issue.number }}.clerkpreview.com --token=${{ secrets.VERCEL_CLERK_COOKIE_TOKEN }} --scope clerk-production + echo "stable_url=https://javascript-preview-${{ github.event.issue.number }}.clerkpreview.com" >> $GITHUB_OUTPUT - - name: Create preview comment - deployed + - name: Create preview comment - Deployed uses: marocchino/sticky-pull-request-comment@v2.8.0 with: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - number: ${{ github.event.pull_request.number }} + GITHUB_TOKEN: ${{ secrets.CLERK_COOKIE_PAT }} + number: ${{ github.event.issue.number }} header: ${{ env.COMMENT_HEADER }} message: | Hey @${{ github.event.comment.user.login }}, your preview is available. diff --git a/docs/CICD.md b/docs/CICD.md index 3bb1db9ef7..4e60d76eab 100644 --- a/docs/CICD.md +++ b/docs/CICD.md @@ -32,8 +32,8 @@ For more details about canary releases, refer to [PUBLISH.md](https://github.com Every time a PR opens or a PR is merged into `main`, the workflows defined in `.github/workflows` will run, ensuring: -- all packages build correctly using Node@18 and Node@19 -- all tests pass using Node@18 and Node@19 +- all packages build correctly +- all unit and integration tests are passing - no type issues exist using `TSC` - no lint issues exist - formatting is consistent @@ -41,4 +41,4 @@ Every time a PR opens or a PR is merged into `main`, the workflows defined in `. ## Misc - The `labeler` workflow automatically adds tags to all PRs according to the packages they affect -- The `lock-threads` workflow runs on a schedule and automatically locks stale PRs and Issues. +- The `lock-threads` workflow runs on a schedule and automatically locks stale PRs and issues. diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 3571036875..c68cee259c 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -184,7 +184,7 @@ If you want to add or edit localizations (e.g. how a button text is translated t ## Publishing packages -_Note: Only core maintainers can publish packages._ +_Note: Only Clerk employees can publish packages._ For more information visit [publish documentation](https://github.com/clerk/javascript/blob/main/docs/PUBLISH.md). diff --git a/docs/PUBLISH.md b/docs/PUBLISH.md index d1ff019542..9cffc6ea20 100644 --- a/docs/PUBLISH.md +++ b/docs/PUBLISH.md @@ -1,6 +1,6 @@ # Publishing packages -_Note: Only core maintainers can publish packages._ +_Note: Only Clerk employees can trigger the actions described below._ ## Publishing stable package versions (`@latest`) @@ -19,15 +19,15 @@ An automated canary release will be take place every time a PR gets merged into - During a canary release, `@clerk/clerk-js` will also be released. If needed, use the `clerkJSVersion` prop to use a specific version, eg: `` - A package will not be published if it's not affected by a changeset. +**Note:** If the `main` branch is in [prerelease mode](https://github.com/changesets/changesets/blob/main/docs/prereleases.md) merges into the latest `release/` branch will be released under the `@canary` tag. + ## Publishing snapshot package versions (`@snapshot`) Snapshot releases are a way to release your changes for testing without updating the versions or waiting for your PR to be merged into `main`. This is especially useful when you want to test your changes in a cloud environment that does not offer a way to upload prebuilt artifacts of your app or if you want to test the end-to-end flow as a user, without relying on local linking to test. Snapshot releases can also be used as a tool for customers to verify a fix on their machines. -**Important:** -Before requesting a snapshot release, ensure that your Clerk organization membership status is set to "Public". Otherwise, the snapshot release will fail. To set your status to "Public", follow [these steps](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/publicizing-or-hiding-organization-membership). +**Important:** Before requesting a snapshot release, ensure that your Clerk organization membership status is set to "Public". Otherwise, the snapshot release will fail. To set your status to "Public", follow [these steps](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/publicizing-or-hiding-organization-membership). -**Important:** -When using a snapshot release, it's highly recommended you install a specific version directly (eg `npm i @clerk/nextjs@4.27.0-snapshot.v609cd23`). Do not use the `@snapshot` tag to get the most recent snapshot release, as this will result in unexpected behavior when another member publishes their own snapshot. +**Important:** When using a snapshot release, it's highly recommended you install a specific version directly (eg `npm i @clerk/nextjs@4.27.0-snapshot.v609cd23`). Do not use the `@snapshot` tag to get the most recent snapshot release, as this will result in unexpected behavior when another member publishes their own snapshot. To perform a snapshot release, simply comment `!snapshot` in your PR. Once the packages are built and published (~2mins), [clerk-cookie](https://github.com/clerk-cookie) will post a reply with the published versions ([example](https://github.com/clerk/javascript/pull/1329#issuecomment-1586970784)). Simply install the snap version using `npm install` as usual. @@ -40,10 +40,6 @@ Notes: - To make iterations faster, tests will not run for snapshot versions. - A package will not be published if it's not affected by a changeset. -## Publishing canary package versions (`@canary`) - -We're still considering whether switching the repo into a `canary` mode for big, experimental features makes sense. There is no use case for this right now, however, we might experiment with the [changesets prerelease mode](https://github.com/changesets/changesets/blob/main/docs/prereleases.md) in the future. - ## Backporting PRs > Backporting is the action of taking parts from a newer version of a software system or software component and porting them to an older version of the same software. @@ -57,3 +53,13 @@ node backports.mjs release/v4 1234 ``` The command above will backport the PR `1234` to the branch `release/v4`. + +## Previewing PRs + +Deploy previews enable you to give yourself and others reviewing the PR a chance to see your changes deployed in a live environment. Your changes are applied to a test site and deployed to a URL one can visit. This is especially helpful for e.g. visual changes made inside the UI components. + +**Important:** Before requesting a deploy preview, ensure that your Clerk organization membership status is set to "Public". Otherwise, the preview will fail. To set your status to "Public", follow [these steps](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/publicizing-or-hiding-organization-membership). + +You can request a deploy preview by commenting `!preview` in your PR. A GitHub workflow will take your current PR, install the current state of the packages into a test site, and deploy that test site to Vercel. Once the deployment is done, a GitHub comment will point you to the deployed URL. + +**Important:** In order for you (or others) to visit the preview URL, you’ll need to be part of the Clerk Vercel team and logged into Vercel.