feat(v9): backport openapi tooling etc. from v10 (#1145)

## 🧰 Changes reapplies the following changes from the `next` branch onto the `v9` branch: - [x] #1124 - [x] #1125 - [x] #1126 - [x] #1127 - [x] #1143 - [x] #1144 - [x] #1141 ## 🧬 QA & Testing do tests pass? --------- Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: Jon Ursenbach <[email protected]> Co-authored-by: semantic-release-bot <[email protected]> Co-authored-by: Jon Ursenbach <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
readmeio · Jan 6, 2025 · 14828db · 14828db
1 parent 3588c5a
commit 14828db
Show file tree

Hide file tree

Showing 17 changed files with 2,258 additions and 1,804 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -87,15 +87,42 @@ act -j simple
 
 ### Usage of `console`
 
+<details>
+
+<summary>⚠️ <b>Outdated guidance</b> (you'll notice we still use this paradigm in a few commands, but don't use this guidance for new commands!)</summary>
+
 As you'll learn in our commands logic (see [`bin/run.js`](bin/run.js) and the [`src/commands`](src/commands) directory), we wrap our command outputs in resolved/rejected [`Promise` objects](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) and use [`bin/run.js`](bin/run.js) file to log the results to the console and return the correct status code. This is so we can write more resilient tests, ensure that the proper exit codes are being returned, and make debugging easier.
 
 When writing command logic, avoid using `console` statements (and correspondingly, avoid mocking `console` statements in tests) when possible.
 
+</details>
+
+<details open>
+
+<summary><b>Updated Guidance</b></summary>
+
+When writing command logic, avoid using `console` statements. As modeled by [the `openapi upload` command](https://github.com/readmeio/rdme/blob/1e199064b0418b11b56ce08bad3d96ff2bead10c/src/commands/openapi/upload.ts) (only available in `v10` and above), we use [`oclif`'s command methods](https://oclif.io/docs/commands/#command-methods) for writing to the console. This allows us to seamlessly integrate [`oclif`'s support for JSON output](https://oclif.io/docs/json/).
+
+[The `@oclif/test` helper](https://github.com/oclif/test) automatically mocks any writes to `stdout` or `stderr`. This is great for properly asserting `rdme` outputs, but can be a bit confusing to develop with at first if you rely on `console.log` as part of your debugging since those statements won't get written to the console the way you'd expect.
+
+If you rely on `console.log` (or something similar) during development, you can do the following to view your output:
+
+1. Make sure you're using the `runCommand` helper in [this file](https://github.com/readmeio/rdme/blob/1e199064b0418b11b56ce08bad3d96ff2bead10c/__tests__/helpers/oclif.ts) and **not** `runCommandAndReturnResult`. See [this test file](https://github.com/readmeio/rdme/blob/1e199064b0418b11b56ce08bad3d96ff2bead10c/__tests__/commands/openapi/upload.test.ts) for an example.
+
+2. Add a statement like this in your test:
+
+   ```js
+   const result = await run(['--key', key]); // add any other flags here as needed
+   expect(result).toStrictEqual({}); // this will fail, but it will output the entire result object, which you can inspect
+   ```
+
+</details>
+
 <img align="right" width="25%" style="margin-bottom: 2em" src="https://owlbertsio-resized.s3.amazonaws.com/Blocks.psd.png">
 
 ### Making `fetch` requests
 
-`fetch` requests are very common in this codebase. When sending `fetch` requests to the ReadMe API (i.e., [dash.readme.com](https://dash.readme.com)), make sure to use the `fetch` wrapper function located in [`src/lib/readmeAPIFetch.ts`](src/lib/readmeAPIFetch.ts). We have an ESLint rule to flag this.
+`fetch` requests are very common in this codebase. When sending `fetch` requests to the ReadMe API (i.e., [dash.readme.com](https://dash.readme.com) or [api.readme.com](https://api.readme.com)), make sure to use the `fetch` wrapper function located in [`src/lib/readmeAPIFetch.ts`](src/lib/readmeAPIFetch.ts).
 
 In that wrapper function, we set several important request headers and configure the proxy, if the user added one via `HTTPS_PROXY`.
 

diff --git a/MAINTAINERS.md b/MAINTAINERS.md
@@ -13,7 +13,7 @@ When code is merged into the `main` or `next` branches, a release workflow (powe
 
 - All commit messages since the last release are analyzed to determine whether or not the new changes warrant a new release (i.e., if the changes are features or fixes as opposed to smaller housekeeping changes) 🧐
 - Based on the changes, the version is bumped in [`package.json`](./package.json) 🥊 For example, say the current version is `8.5.1` and the commit history includes a new feature. This would result in a minor semver bump, which would produce the following tags:
-  - A release tag like `v8.6.0` if on the `main` branch
+  - A release tag like `v8.6.0` if on the `main` or `v9` branches
   - A prerelease tag like `v8.6.0-next.1` if on the `next` branch
 - A few other files, such as [`CHANGELOG.md`](./CHANGELOG.md), [the command reference pages](./documentation/commands), and our GitHub Actions bundle files, are updated based on this code 🪵
 - A build commit (like [this](https://github.com/readmeio/rdme/commit/533a2db50b39c3b6130b3af07bebaed38218db4c)) is created with all of the updated files (e.g., `package.json`, `CHANGELOG.md`, etc.) 🆕
@@ -22,9 +22,39 @@ When code is merged into the `main` or `next` branches, a release workflow (powe
 - The new version is published to the `npm` registry 🚀 The package [distribution tag](https://docs.npmjs.com/adding-dist-tags-to-packages) will depend on which branch is being pushed to:
   - If on the `main` branch, a version is pushed on the main distribution tag (a.k.a. `latest`, which is used when someone runs `npm i rdme` with no other specifiers).
   - If on the `next` branch, the prerelease distribution tag (a.k.a. [`next`](https://www.npmjs.com/package/rdme/v/next)) is updated.
+  - If on the `v9` branch, there is no distribution tag, but any minor/patch changes on this branch are automatically released to the 9.x release channel.
 - A [GitHub release is created](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release) for the tag 🐙
 - If on the `main` branch, the new changes are backported to the `next` branch so both branches remain in sync 🔄
 
+### Maintaining two major release channels
+
+We maintain two different release channels:
+
+- one for `v9` (so we can have a release that supports all functionality pre-ReadMe Refactored, more in [our migration guide](./documentation/migration-guide.md))
+- one for the latest release (`v10`, as of this writing — `v10` and onward are for customers on ReadMe Refactored only)
+
+All new feature development should be on the `next` branch. If the feature does not interact with the ReadMe API in anyway (e.g., a docs change, an OpenAPI utility command), we can backport the change to the `v9` branch.
+
+Here's the recommended approach:
+
+1. Once the pull request has been merged into `next`, grab the merge commit SHA.
+2. Check out the `v9` branch, create a new branch based off of that branch, and cherry-pick the aformentioned commit SHA:
+
+   ```sh
+   git checkout v9
+   git checkout -b my-v9-backport-branch
+   git cherry-pick SHA
+   ```
+
+3. Create a new pull request and set the base branch to `v9`.
+4. Once CI passes and you get the necessary approvals, merge that pull request in.
+5. The final step ensures that everything in the `next` branch is a superset of everything in the `v9` branch. To do this, checkout the `next` branch and merge `v9` into it.
+
+   ```sh
+   git checkout next
+   git merge v9
+   ```
+
 ## One more thing ☝️
 
 > [!NOTE]

diff --git a/README.md b/README.md
@@ -137,7 +137,7 @@ To set this up, check out [1Password's documentation on the ReadMe shell plugin]
 
 ```sh
 export HTTPS_PROXY=https://proxy.example.com:5678
-rdme openapi
+rdme login
 ```
 
 # GitHub Actions Configuration
@@ -148,7 +148,7 @@ rdme openapi
 For usage in [GitHub Actions](https://docs.github.com/actions), you can create a new GitHub Actions workflow file by installing the CLI on your local machine and running the the command you wish to run in GitHub Actions, along with the `--github` flag. For example:
 
 ```sh
-rdme openapi --github
+rdme openapi validate --github
 ```
 
 This will run through the `openapi` command, ask you a few quick questions, and then automatically create a fully functional GitHub Actions workflow file for you. 🪄