@mintlify/cli 4.0.539 → 4.0.540

package/CONTRIBUTING.md

@@ -14,28 +14,32 @@ If you wish to continue using the production version of the CLI, you will need t
 
 ## Updating Version of Mint Client
 
-The CLI uses GitHub releases to download specific versions of the client code used in `mintlify dev`. Older CLI versions will continue using the client code they were bundled with. Users need to update to a newer version of the CLI to get the newest client code. CLI contributors bump the client version used by the CLI whenever there are major changes.
-
-Here's how to publish new client changes to the CLI:
-
-1. In `mint/packages/previewing/src/constants.ts`, update the value of `TARGET_MINT_VERSION` to match the current version of the client package (`mint/apps/client/package.json`). ([example PR](https://github.com/mintlify/mint/pull/770/files#diff-d8424b340a10b1927bea6b52668d2d83dd49e0c563dde8716274a639edac8a9f), but you should only need to change `constants.ts`)
-2. Commit change and push branch to github.
-3. Create PR, copy/pasting the following test plan:
-
-```
-- [ ] uninstall global mintlify with `npm uninstall -g mintlify`
-- [ ] `cd` to `mint/packages/mintlify` and link with `npm link`
-- [ ] build from `mint` folder with `yarn build`
-- [ ] clear out any existing downloaded zip with `rm -rf ~/.mintlify`
-- [ ] `cd` to a docs folder
-- [ ] run `mintlify dev`
-- [ ] confirm new CLI behavior is observed
-```
-
-4. Start a new `Upload Standalone zip` workflow. **BE SURE TO SPECIFY YOUR PR BRANCH** and the new client version number.
-   <img width="800" alt="Screenshot 2023-04-24 at 10 03 15 PM" src="https://user-images.githubusercontent.com/63772591/234178961-ab33c765-8b42-41e8-942f-f0a929d7abbf.png">
-5. Execute test plan.
-6. Merge PR.
-7. Wait for `Bump packages` workflow to succeed on your squashed commit. At this point, all npm packages have been updated, and you can use the new version by running `npm update -g mintlify`.
-8. Lastly, download the zip from bunny.net and create a new GitHub release with the given version. Click on `Generate release notes` to auto-populate the description.
-   <img width="800" alt="Screenshot 2023-04-24 at 10 10 26 PM" src="https://user-images.githubusercontent.com/63772591/234179953-9d0976db-9a3b-4678-b844-245b95385671.png">
+The CLI uses GitHub releases to download specific versions of the client code used in `mintlify dev`. It will attempt to fetch the latest version of the client app specified by our [`mint-version.txt`](https://d1ctpt7j8wusba.cloudfront.net/mint-version.txt) file. The mint-version.txt and compressed versions of the client live in S3 under `mint-client-releases`.
+
+Here's how new client changes are published, they should usually require no manual intervention:
+
+1. When a PR is merged to main, we check whether or not the client app or any of its dependencies have changed with the `check-changes` workflow job
+2. The `bump-packages` job always runs, which increments the version of any package that has changed in our monorepo packages, commits the version increment to github, and publishes the update to npm
+3. If `check-changes` detected a client change, the `client-release` workflow is triggered after `bump-packages`
+4. The `client-release` workflow creates a standalone zip of the client app and uploads it to S3 as mint-${version}.tar.gz
+5. The `cli-test` workflow is triggered, which uses a local build of the CLI package and the new client version that was just zipped and shipped. It tests the CLI output has not changed (no new errors) and that the starter-kit passes some simple Puppeteer tests.
+6. If the `cli-test` workflow passes, the `update-release-version` workflow is triggered, which uploads an updated version of the mint-version.txt file to S3 with the new version number, and invalidates the cache for that file.
+
+## Manually triggering a client release and version update
+
+You can still create a new client version whenever by dispatching the `client-release` workflow from the [Actions tab for the mint repo](https://github.com/mintlify/mint/actions). Click the "Run workflow" dropdown button and enter the version number you want to set it to, then click the green "Run workflow" button. This should run the steps 4-6 detailed above, creating a new package of the client app and updating the version number used by the CLI.
+
+## Manually updating the version of the client app used by the CLI
+
+If for some reason we need to roll back a client version, we can update the mint-version.txt file to swiftly change which version is downloaded by the CLI. This can be done 2 ways:
+
+1. Via github workflow: Go to the [Actions tab for the mint repo](https://github.com/mintlify/mint/actions) and select the Update Release Version workflow. Click the "Run workflow" dropdown button and enter the version number you want to set it to, then click the green "Run workflow" button.
+2. Manually: If you have S3 access, simply upload a new version of the mint-version.txt file in the `mint-client-releases` folder
+
+## Manually uploading a packaged version of the client app
+
+If for some reason the release workflow is broken or we can't access AWS programmatically, the newly zipped version of the client app is retained in the `client-release` workflow as a Github artifact for 1 day. We can download it manually from Github after the release and upload it wherever needed.
+
+## Manually overriding the client version used locally
+
+Run `mintlify dev --client-version x.x.xxxx` with the client version you would like to use and that version will be downloaded instead of the latest client version.