feat!: v10 release (#1113)

## 🧰 Changes

this PR aggregates all of the PRs going out as part of the v10 release
(i.e, the second section of PRs below). all PRs should be reviewed prior
to being merged into this branch.

### outstanding tasks

#### needs to go out _before_ v10 is released (i.e., in the v9 release
channel)
- [x] #1082


#### needs to go out as part of v10 release
- [x] `openapi upload`
  - [x] #1111
  - [x] #1116
- [x] #1107
- [x] #1104
- [x] #1108

#### merge into `v9` branch once `v10` release is successfully released
- [ ] #1121

#### double-check these things before merging

- [x] swap out any links to the `v9` docs (e.g., `/tree/v9`) with `v10`
as needed
(b19416d)
- [x] make sure all API v1 requests in `v10` will work
- [x] make sure v10 migration guide reflects the final design decisions
around `openapi upload`

## ⚠️ Breaking Changes

<sub>listing all of the breaking changes 1 by 1 below so they get picked
up by semantic release...</sub>

BREAKING CHANGE: `categories`, `custompages`, `docs` and `versions` have
now been removed. Please use a bidirectional syncing workflow instead.
Read more in [our migration
guide](https://github.com/readmeio/rdme/tree/v10/documentation/migration-guide.md).

BREAKING CHANGE: `rdme openapi` has been replaced by `rdme openapi
upload`. Read more in [our migration
guide](https://github.com/readmeio/rdme/tree/v10/documentation/migration-guide.md).

.github/workflows/ci.yml

@@ -103,21 +103,32 @@ jobs:
         if: ${{ steps.openapi-validate-fail.outcome == 'success' }}
         run: echo "::error::Expected validation in previous step to fail" && exit 1
 
-      # Docs: https://rdme-test.readme.io
-      - name: Run `openapi` command
-        uses: ./rdme-repo/
-        with:
-          rdme: openapi oas-examples-repo/3.1/json/petstore.json --key=${{ secrets.RDME_TEST_PROJECT_API_KEY }} --id=${{ secrets.RDME_TEST_PROJECT_API_SETTING }}
-
-      - name: Run `openapi` command with weird arg syntax
-        uses: ./rdme-repo/
-        with:
-          rdme: openapi "oas-examples-repo/3.1/json/petstore.json" --key "${{ secrets.RDME_TEST_PROJECT_API_KEY }}" --id=${{ secrets.RDME_TEST_PROJECT_API_SETTING }}
-
       # this is a test to ensure that the rdme github action can run properly
       # the way that our users invoke it
       - name: E2E run of `openapi validate` on `next` branch
         uses: readmeio/rdme@next
         if: ${{ github.ref }} == 'refs/heads/next'
         with:
           rdme: openapi validate oas-examples-repo/3.1/json/petstore.json
+
+      # Docs: https://rdme-test.readme.io
+      - name: Run `openapi` command
+        uses: ./rdme-repo/
+        with:
+          rdme: openapi upload oas-examples-repo/3.1/json/petstore.json --key=${{ secrets.RDME_REFACTORED_TEST_PROJECT_API_KEY }}
+      - name: Run `openapi` command with env var
+        uses: ./rdme-repo/
+        with:
+          rdme: openapi upload oas-examples-repo/3.1/json/petstore.json
+        env:
+          RDME_API_KEY: ${{ secrets.RDME_REFACTORED_TEST_PROJECT_API_KEY }}
+      - name: Run `openapi` command with other env var
+        uses: ./rdme-repo/
+        with:
+          rdme: openapi upload oas-examples-repo/3.1/json/petstore.json
+        env:
+          README_API_KEY: ${{ secrets.RDME_REFACTORED_TEST_PROJECT_API_KEY }}
+      - name: Run `openapi` command with weird arg syntax
+        uses: ./rdme-repo/
+        with:
+          rdme: openapi upload "oas-examples-repo/3.1/json/petstore.json" --key "${{ secrets.RDME_REFACTORED_TEST_PROJECT_API_KEY }}"

.github/workflows/docs.yml

@@ -1,7 +1,10 @@
 name: Sync `documentation` directory to ReadMe
 
 # Run workflow for every push
-on: push
+on:
+  push:
+    branches:
+      - main
 
 jobs:
   sync:
@@ -40,33 +43,7 @@ jobs:
           regex: false
           include: documentation/*
 
-      # Since this workflow file is in the `rdme` repository itself,
-      # we need to test the GitHub Action using the current commit.
-      # This step builds the `rdme` action code so we can do that.
-      #
-      # This step is not required for syncing your docs to ReadMe!
-      - name: Rebuild GitHub Action for testing purposes
-        run: npm run build:gha
-
-      # And finally, with our updated documentation,
-      # we run the `rdme` GitHub Action to sync the Markdown file
-      # in the `documentation` directory.
-      # Here's the page we're syncing: https://docs.readme.com/docs/rdme
-
-      # First we're going to perform a dry run of syncing process.
-      # We do this on every push to ensure that an actual sync will work properly
-      - name: Sync docs to ReadMe (dry run)
-        uses: ./
-        with:
-          rdme: docs ./documentation --key=${{ secrets.README_DEVELOPERS_API_KEY }} --version=${{ vars.README_DEVELOPERS_MAIN_VERSION }} --dryRun
-
-      # And finally, we perform an actual sync to ReadMe if we're on the main branch
       - name: Sync docs to ReadMe
-        if: github.event_name == 'push' && github.event.ref == 'refs/heads/main'
-        # We use the `main` branch as ref for GitHub Action
-        # This is NOT recommended, as it can break your workflows without notice!
-        # We recommend specifying a fixed version, i.e. @8.0.0
-        # Docs: https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions#example-using-versioned-actions
-        uses: readmeio/rdme@main
+        uses: readmeio/rdme@v9
         with:
           rdme: docs ./documentation --key=${{ secrets.README_DEVELOPERS_API_KEY }} --version=${{ vars.README_DEVELOPERS_MAIN_VERSION }}

README.md

@@ -15,12 +15,12 @@
   <a href="https://readme.com"><img src="https://raw.githubusercontent.com/readmeio/.github/main/oss-badge.svg" /></a>
 </p>
 
-With `rdme`, you can manage your API definition (we support [OpenAPI](https://spec.openapis.org/oas/v3.1.0.html), [Swagger](https://swagger.io/specification/v2/), and [Postman](https://schema.postman.com/)) and sync it to your API reference docs on ReadMe. You can also access other parts of [ReadMe's RESTful API](https://docs.readme.com/reference), including syncing Markdown documentation with your ReadMe project and managing project versions.
+With `rdme`, you can manage your API definition (we support [OpenAPI](https://spec.openapis.org/oas/v3.1.0.html), [Swagger](https://swagger.io/specification/v2/), and [Postman](https://schema.postman.com/)) and sync it to your API reference docs on ReadMe.
 
 Not using ReadMe for your docs? No worries. `rdme` has a variety of tools to help you identify issues with your API definition — no ReadMe account required.
 
-> [!WARNING]
-> Heads up: our [new ReadMe Refactored experience](https://docs.readme.com/main/docs/welcome-to-readme-refactored) doesn’t yet support `rdme`. If your project is using the new ReadMe Refactored experience, we recommend [enabling bi-directional syncing via Git](https://docs.readme.com/main/docs/bi-directional-sync) for an even better editing experience for the technical and non-technical users on your team!
+> [!NOTE]
+> If you're using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored), you'll want to use `rdme@10` or later. If you're **not** using ReadMe Refactored, you'll want to use `rdme@9`. More info can be found in our [migration guide](https://github.com/readmeio/rdme/blob/next/documentation/migration-guide.md).
 
 # Table of Contents
 
@@ -170,16 +170,15 @@ npm run build && npm run build:docs
 # Command Topics
 
 * [`rdme autocomplete`](documentation/commands/autocomplete.md) - Display autocomplete installation instructions.
-* [`rdme categories`](documentation/commands/categories.md) - List or create categories in your ReadMe developer hub.
 * [`rdme changelogs`](documentation/commands/changelogs.md) - Sync Markdown files to your ReadMe project as Changelog posts.
-* [`rdme custompages`](documentation/commands/custompages.md) - Sync Markdown/HTML files to your ReadMe project as Custom Pages.
-* [`rdme docs`](documentation/commands/docs.md) - Sync or prune Guides pages in your ReadMe developer hub.
 * [`rdme help`](documentation/commands/help.md) - Display help for rdme.
 * [`rdme login`](documentation/commands/login.md) - Login to a ReadMe project.
 * [`rdme logout`](documentation/commands/logout.md) - Logs the currently authenticated user out of ReadMe.
 * [`rdme openapi`](documentation/commands/openapi.md) - Manage your API definition (e.g., syncing, validation, analysis, conversion, etc.). Supports OpenAPI, Swagger, and Postman collections, in either JSON or YAML formats.
-* [`rdme versions`](documentation/commands/versions.md) - Manage your documentation versions.
 * [`rdme whoami`](documentation/commands/whoami.md) - Displays the current user and project authenticated with ReadMe.
 
 <!-- commandsstop -->
 <!-- prettier-ignore-end -->
+
+> [!IMPORTANT]
+> You'll notice that several previous `rdme` commands are no longer present. That's because this version is for projects that use [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored) and [bi-directional syncing](https://docs.readme.com/main/docs/bi-directional-sync) is the recommended approach for most workflows previously managed via `rdme`. See more in [our migration guide](./documentation/migration-guide.md).