From 9ac1a4c50c85efc357014a206b0b00bc0b942278 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Wed, 2 Apr 2025 17:05:20 -0500 Subject: [PATCH 1/6] docs: deprecation notice tweaks --- src/commands/docs/index.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/commands/docs/index.ts b/src/commands/docs/index.ts index 97d7a27be..df08b5587 100644 --- a/src/commands/docs/index.ts +++ b/src/commands/docs/index.ts @@ -15,7 +15,7 @@ export default class DocsCommand extends BaseCommand { static state = 'deprecated'; static deprecationOptions = { - message: `\`rdme ${this.id}\` is deprecated and will be removed in v10. For more information, please visit our migration guide: https://github.com/readmeio/rdme/tree/v9/documentation/migration-guide.md`, + message: `\`rdme ${this.id}\` is deprecated and v10 will have a replacement command that supports ReadMe Refactored. For more information, please visit our migration guide: https://github.com/readmeio/rdme/tree/v9/documentation/migration-guide.md`, }; static aliases = ['guides']; From 70cb5bb4c0839119c3ff4cdcfe2dc91d93258521 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Wed, 2 Apr 2025 17:06:08 -0500 Subject: [PATCH 2/6] docs: migration guide updates --- documentation/migration-guide.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/documentation/migration-guide.md b/documentation/migration-guide.md index c289c4cd3..2d3126cca 100644 --- a/documentation/migration-guide.md +++ b/documentation/migration-guide.md @@ -114,15 +114,17 @@ If you're using the `rdme` GitHub Action, update your GitHub Actions workflow fi 5. **Deprecated commands** - The following commands (and their subcommands) will be removed in `rdme@10`: + The following commands (and their subcommands) have been removed in `rdme@10` (see [the `rdme@10` section above](#migrating-to-rdme10) for more info): - `categories` - `custompages` - - `docs` (and its `guides` alias) - `versions` - `open` - The `openapi` command is deprecated and will be replaced in `rdme@10` by a command with a simpler flag setup based on community feedback. + The following commands are deprecated in their current form and have been replaced in `rdme@10` (see [the `rdme@10` section above](#migrating-to-rdme10) for more info): + + - `openapi` is replaced by `openapi upload` + - `docs` is replaced by `docs upload` 6. **Verify any scripts that utilize raw CLI outputs** From e22822e9990e7460c892757eb7ed9d8df915453c Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Fri, 4 Apr 2025 09:58:18 -0500 Subject: [PATCH 3/6] docs: update links --- README.md | 2 +- documentation/legacy/github-actions-docs-example.md | 2 +- documentation/legacy/github-actions-openapi-example.md | 2 +- documentation/legacy/rdme.md | 8 ++++---- documentation/migration-guide.md | 10 +++++----- 5 files changed, 12 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 164ded66f..e5d34a9d8 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ With `rdme`, you can manage your API definition (we support [OpenAPI](https://sp 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] -> If you're using the [new ReadMe Refactored experience](https://docs.readme.com/main/docs/welcome-to-readme-refactored), you'll want to use `rdme@10` instead. Head over to [our migration guide](https://github.com/readmeio/rdme/blob/next/documentation/migration-guide.md) for more information. +> If you're using the [new ReadMe Refactored experience](https://docs.readme.com/main/docs/migration), you'll want to use `rdme@10` instead. Head over to [our migration guide](https://github.com/readmeio/rdme/blob/next/documentation/migration-guide.md) for more information. # Table of Contents diff --git a/documentation/legacy/github-actions-docs-example.md b/documentation/legacy/github-actions-docs-example.md index a140349e6..b19a64b14 100644 --- a/documentation/legacy/github-actions-docs-example.md +++ b/documentation/legacy/github-actions-docs-example.md @@ -19,7 +19,7 @@ Check out `.github/workflows/docs.yml` for more info on this! > 🚧 Deprecated Guidance > -> This example is only applicable for projects that have yet to migrate to [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored), which requires `rdme@9`. You can find more info in [our `rdme` migration guide](https://github.com/readmeio/rdme/blob/next/documentation/migration-guide.md) or by reaching out to us at [support@readme.io](mailto:support@readme.io). +> This example is only applicable for projects that have yet to migrate to [ReadMe Refactored](https://docs.readme.com/main/docs/migration), which requires `rdme@9`. You can find more info in [our `rdme` migration guide](https://github.com/readmeio/rdme/blob/next/documentation/migration-guide.md) or by reaching out to us at [support@readme.io](mailto:support@readme.io). > > We will be updating this document with our latest guidance soon. Thanks for your patience! diff --git a/documentation/legacy/github-actions-openapi-example.md b/documentation/legacy/github-actions-openapi-example.md index 10fa65a12..081d1fe46 100644 --- a/documentation/legacy/github-actions-openapi-example.md +++ b/documentation/legacy/github-actions-openapi-example.md @@ -18,7 +18,7 @@ Check out `.github/workflows/docs.yml` for more info on this! > 🚧 Deprecated Guidance > -> This example is only applicable for projects that have yet to migrate to [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored), which requires `rdme@9`. You can find more info in [our `rdme` migration guide](https://github.com/readmeio/rdme/blob/next/documentation/migration-guide.md) or by reaching out to us at [support@readme.io](mailto:support@readme.io). +> This example is only applicable for projects that have yet to migrate to [ReadMe Refactored](https://docs.readme.com/main/docs/migration), which requires `rdme@9`. You can find more info in [our `rdme` migration guide](https://github.com/readmeio/rdme/blob/next/documentation/migration-guide.md) or by reaching out to us at [support@readme.io](mailto:support@readme.io). > > We will be updating this document with our latest guidance soon. Thanks for your patience! diff --git a/documentation/legacy/rdme.md b/documentation/legacy/rdme.md index 6097a3749..9c51f3141 100644 --- a/documentation/legacy/rdme.md +++ b/documentation/legacy/rdme.md @@ -47,7 +47,7 @@ With `rdme`, you can create workflows for a variety of use cases, including: > 🚧 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! +> Our [new ReadMe Refactored experience](https://docs.readme.com/main/docs/migration) 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! ## General Setup and Usage @@ -57,7 +57,7 @@ To see detailed CLI setup instructions and all available commands, check out [th > 🚧 Deprecated Guidance > -> This guidance is only applicable for projects that have yet to migrate to [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored), which requires `rdme@9`. You can find more info in [our `rdme` migration guide](https://github.com/readmeio/rdme/blob/next/documentation/migration-guide.md) or by reaching out to us at [support@readme.io](mailto:support@readme.io). +> This guidance is only applicable for projects that have yet to migrate to [ReadMe Refactored](https://docs.readme.com/main/docs/migration), which requires `rdme@9`. You can find more info in [our `rdme` migration guide](https://github.com/readmeio/rdme/blob/next/documentation/migration-guide.md) or by reaching out to us at [support@readme.io](mailto:support@readme.io). > > We will be updating this document with our latest guidance soon. Thanks for your patience! @@ -147,7 +147,7 @@ While there are [dozens of event options available](https://docs.github.com/acti > 🚧 Deprecated Guidance > -> This guidance is only applicable for projects that have yet to migrate to [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored), which requires `rdme@9`. You can find more info in [our `rdme` migration guide](https://github.com/readmeio/rdme/blob/next/documentation/migration-guide.md) or by reaching out to us at [support@readme.io](mailto:support@readme.io). +> This guidance is only applicable for projects that have yet to migrate to [ReadMe Refactored](https://docs.readme.com/main/docs/migration), which requires `rdme@9`. You can find more info in [our `rdme` migration guide](https://github.com/readmeio/rdme/blob/next/documentation/migration-guide.md) or by reaching out to us at [support@readme.io](mailto:support@readme.io). > > We will be updating this document with our latest guidance soon. Thanks for your patience! @@ -227,7 +227,7 @@ The following section has links to full GitHub Actions workflow file examples. > 🚧 Deprecated Guidance > -> This guidance is only applicable for projects that have yet to migrate to [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored), which requires `rdme@9`. You can find more info in [our `rdme` migration guide](https://github.com/readmeio/rdme/blob/next/documentation/migration-guide.md) or by reaching out to us at [support@readme.io](mailto:support@readme.io). +> This guidance is only applicable for projects that have yet to migrate to [ReadMe Refactored](https://docs.readme.com/main/docs/migration), which requires `rdme@9`. You can find more info in [our `rdme` migration guide](https://github.com/readmeio/rdme/blob/next/documentation/migration-guide.md) or by reaching out to us at [support@readme.io](mailto:support@readme.io). > > We will be updating this document with our latest guidance soon. Thanks for your patience! diff --git a/documentation/migration-guide.md b/documentation/migration-guide.md index 2d3126cca..7c0020e6b 100644 --- a/documentation/migration-guide.md +++ b/documentation/migration-guide.md @@ -1,8 +1,8 @@ # Migration Guide -This guide helps you migrate your ReadMe CLI (`rdme`) setup to the latest version and prepare for future versions. Choose your migration path based on whether you're using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored). +This guide helps you migrate your ReadMe CLI (`rdme`) setup to the latest version and prepare for future versions. Choose your migration path based on whether you're using [ReadMe Refactored](https://docs.readme.com/main/docs/migration). -1. If your project is using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored), [use `rdme@v10`](#migrating-to-rdme10) and beyond. +1. If your project is using [ReadMe Refactored](https://docs.readme.com/main/docs/migration), [use `rdme@v10`](#migrating-to-rdme10) and beyond. 2. If your project is **not** yet using ReadMe Refactored, [use `rdme@v9`](#migrating-to-rdme9). The `v9` channel will continue to be maintained while we focus on making sure that everybody can upgrade their ReadMe projects to ReadMe Refactored. ## Table of Contents @@ -53,7 +53,7 @@ This release adds a few features that make it even easier to get started with `r > [!NOTE] -> `rdme@9` only works with ReadMe projects that are **not** using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored). If you are using ReadMe Refactored, [you'll want to use `rdme@10`](#migrating-to-rdme10). +> `rdme@9` only works with ReadMe projects that are **not** using [ReadMe Refactored](https://docs.readme.com/main/docs/migration). If you are using ReadMe Refactored, [you'll want to use `rdme@10`](#migrating-to-rdme10). ### Upgrading to `v9` @@ -140,9 +140,9 @@ Please see [the `rdme@8.0.0` release notes](https://github.com/readmeio/rdme/rel | Feature | `v8` | `v9` | `v10` | | ------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ----------- | ----------- | | Actively Maintained? | ❌ | βœ… | βœ… | -| Support for [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored)\* | ❌ | ❌ | βœ… | +| Support for [ReadMe Refactored](https://docs.readme.com/main/docs/migration)\* | ❌ | ❌ | βœ… | | Supports Bi-Directional Sync | ❌ | ❌ | βœ… | -| Support for Legacy Projects (i.e., not yet migrated to [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored)) | βœ… | βœ… | ❌ | +| Support for Legacy Projects (i.e., not yet migrated to [ReadMe Refactored](https://docs.readme.com/main/docs/migration)) | βœ… | βœ… | ❌ | | Node.js Requirements | `>=14` | `>=20.10.0` | `>=20.10.0` | \*If you uploaded an API definition prior to migrating your project to ReadMe Refactored, any existing workflows for syncing these files that use a legacy `rdme` version (i.e., `v9` or earlier) should continue to work, even after migrating. **For new workflows, we recommend following this migration guide and upgrading to the latest version.** From a04f7f6fd14e91d6781b2f56885ed869ccfbc4b6 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Fri, 4 Apr 2025 09:59:18 -0500 Subject: [PATCH 4/6] docs: remove all v9 migration guide content --- documentation/migration-guide.md | 94 +------------------------------- 1 file changed, 1 insertion(+), 93 deletions(-) diff --git a/documentation/migration-guide.md b/documentation/migration-guide.md index 7c0020e6b..2fe121734 100644 --- a/documentation/migration-guide.md +++ b/documentation/migration-guide.md @@ -34,103 +34,11 @@ npx markdown-toc documentation/migration-guide.md --maxdepth 2 --bullets="-" -i ## Migrating to `rdme@9` -### Overview - -This release adds a few features that make it even easier to get started with `rdme`: - -1. **Enhanced Command Documentation** - - - Complete command reference in [the `documentation/commands` directory](https://github.com/readmeio/rdme/tree/v9/documentation/commands) - - Detailed usage examples and parameter descriptions - - Structured by command category for intuitive navigation - -2. **Improved CLI Experience** - - - Overhauled help screens with detailed examples to improve readability and ease of use - - Set up CLI autocompletions with [the `autocomplete` command](https://github.com/readmeio/rdme/tree/v9/documentation/commands/autocomplete.md) - - Smart command discovery that helps catch and correct typos - - Redesigned error messages with clear resolution steps - > [!NOTE] -> `rdme@9` only works with ReadMe projects that are **not** using [ReadMe Refactored](https://docs.readme.com/main/docs/migration). If you are using ReadMe Refactored, [you'll want to use `rdme@10`](#migrating-to-rdme10). +> If you have **not** yet migrated ReadMe Refactored, you'll want to use this version, `v9`! The `v9` migration guide can be found [here](https://github.com/readmeio/rdme/blob/v10/documentation/migration-guide.md#migrating-to-rdme9). -### Upgrading to `v9` - -#### Step 1: Upgrade via `npm` - -To install this version of the `rdme` CLI globally, run the following command: - -```sh -npm install -g rdme@9 -``` - -More installation options can be found in [our docs](https://github.com/readmeio/rdme/tree/v9?tab=readme-ov-file#setup). - -#### Step 2: Update GitHub Actions Workflow - -If you're using the `rdme` GitHub Action, update your GitHub Actions workflow file so your `rdme` usage uses the `v9` reference like so: - -```yaml -- uses: readmeio/rdme@v9 - with: - rdme: openapi validate petstore.json -``` - -#### Step 3: Address `v9` Breaking Changes - -1. **Verify your runtime** - - - For CLI users, make sure your Node.js version is up-to-date. The minimum required Node.js version for `rdme@9` is **v20.10.0**. - - The `rdme` release process is no longer publishing Docker images and the GitHub Action is now a JavaScript action. This change should not affect any GitHub Actions users. - -2. **Topic separator changes** - - - The topic separator (i.e., what separates a command from its subcommand) has changed from a colon to a space by default. For example, `rdme openapi:validate` is now `rdme openapi validate`. - - The colon topic separator will continue to be supported so there is no need to change any existing commands, but all documentation and help screens will reflect the space topic separator. - -3. **Command replacements** - - - Replace `swagger` β†’ [`openapi`](https://github.com/readmeio/rdme/tree/v9/documentation/commands/openapi.md#rdme-openapi-spec) - - Replace `validate` β†’ [`openapi validate`](https://github.com/readmeio/rdme/tree/v9/documentation/commands/openapi.md#rdme-openapi-validate-spec) - - Remove: `docs:edit`, `oas` - -4. **Version flag updates** - - The CLI flags on [the `versions create` and `versions update` commands](https://github.com/readmeio/rdme/tree/v9/documentation/commands/versions.md) now maintain parity with [our API flags](https://docs.readme.com/main/reference/createversion). The `--isPublic` flag has been removed in favor of a new flag called `--hidden`, which is the inverse of `--isPublic`. - - **Before** - - ```bash - rdme versions:create 1.0.1 --isPublic true - ``` - - **After** - - ```bash - rdme versions create 1.0.1 --hidden false - ``` - -5. **Deprecated commands** - - The following commands (and their subcommands) have been removed in `rdme@10` (see [the `rdme@10` section above](#migrating-to-rdme10) for more info): - - - `categories` - - `custompages` - - `versions` - - `open` - - The following commands are deprecated in their current form and have been replaced in `rdme@10` (see [the `rdme@10` section above](#migrating-to-rdme10) for more info): - - - `openapi` is replaced by `openapi upload` - - `docs` is replaced by `docs upload` - -6. **Verify any scripts that utilize raw CLI outputs** - - - The underlying architecture for the CLI has been rewritten with [`oclif`](https://oclif.io/), so some command outputs and error messages may look different. - - With the exception of the `--raw` flag on `openapi`, we recommend relying on CLI exit codes in your workflows rather than raw command outputs. - ## Migrating to `rdme@8` Please see [the `rdme@8.0.0` release notes](https://github.com/readmeio/rdme/releases/tag/8.0.0). From 209628a2b9eeea4112a90d82f4f6a9668d7e4b26 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Fri, 4 Apr 2025 10:03:10 -0500 Subject: [PATCH 5/6] docs: update links/format in deprecation messages --- src/commands/categories/create.ts | 2 +- src/commands/categories/index.ts | 2 +- src/commands/custompages.ts | 2 +- src/commands/docs/index.ts | 2 +- src/commands/docs/prune.ts | 2 +- src/commands/open.ts | 2 +- src/commands/openapi/index.ts | 2 +- src/commands/versions/create.ts | 2 +- src/commands/versions/delete.ts | 2 +- src/commands/versions/index.ts | 2 +- src/commands/versions/update.ts | 2 +- 11 files changed, 11 insertions(+), 11 deletions(-) diff --git a/src/commands/categories/create.ts b/src/commands/categories/create.ts index 1bb93f77c..8ab3fc73b 100644 --- a/src/commands/categories/create.ts +++ b/src/commands/categories/create.ts @@ -19,7 +19,7 @@ export default class CategoriesCreateCommand extends BaseCommand { static state = 'deprecated'; static deprecationOptions = { - message: `\`rdme ${this.id}\` is deprecated and v10 will have a replacement command that supports ReadMe Refactored. For more information, please visit our migration guide: https://github.com/readmeio/rdme/tree/v9/documentation/migration-guide.md`, + message: `\`rdme ${this.id}\` is deprecated and v10 will have a replacement command that supports ReadMe Refactored.\n\nFor more information, please visit our migration guide: https://github.com/readmeio/rdme/blob/v10/documentation/migration-guide.md#migrating-to-rdme9`, }; static aliases = ['guides']; diff --git a/src/commands/docs/prune.ts b/src/commands/docs/prune.ts index 0ffcfa35d..514b21ead 100644 --- a/src/commands/docs/prune.ts +++ b/src/commands/docs/prune.ts @@ -23,7 +23,7 @@ export default class DocsPruneCommand extends BaseCommand { static state = 'deprecated'; static deprecationOptions = { - message: `\`rdme ${this.id}\` is deprecated and will be removed in v10. For more information, please visit our migration guide: https://github.com/readmeio/rdme/tree/v9/documentation/migration-guide.md`, + message: `\`rdme ${this.id}\` is deprecated and will be removed in v10.\n\nFor more information, please visit our migration guide: https://github.com/readmeio/rdme/blob/v10/documentation/migration-guide.md#migrating-to-rdme9`, }; async run() { diff --git a/src/commands/openapi/index.ts b/src/commands/openapi/index.ts index 839fb43bf..6925d978f 100644 --- a/src/commands/openapi/index.ts +++ b/src/commands/openapi/index.ts @@ -27,7 +27,7 @@ export default class OpenAPICommand extends BaseCommand { static state = 'deprecated'; static deprecationOptions = { - message: `\`rdme ${this.id}\` is deprecated and v10 will have a replacement command that supports ReadMe Refactored. For more information, please visit our migration guide: https://github.com/readmeio/rdme/tree/v9/documentation/migration-guide.md`, + message: `\`rdme ${this.id}\` is deprecated and v10 will have a replacement command that supports ReadMe Refactored.\n\nFor more information, please visit our migration guide: https://github.com/readmeio/rdme/blob/v10/documentation/migration-guide.md#migrating-to-rdme9`, }; static args = { diff --git a/src/commands/versions/create.ts b/src/commands/versions/create.ts index e86b1c5bb..0c9ece673 100644 --- a/src/commands/versions/create.ts +++ b/src/commands/versions/create.ts @@ -20,7 +20,7 @@ export default class CreateVersionCommand extends BaseCommand static state = 'deprecated'; static deprecationOptions = { - message: `\`rdme ${this.id}\` is deprecated and will be removed in v10. For more information, please visit our migration guide: https://github.com/readmeio/rdme/tree/v9/documentation/migration-guide.md`, + message: `\`rdme ${this.id}\` is deprecated and will be removed in v10.\n\nFor more information, please visit our migration guide: https://github.com/readmeio/rdme/blob/v10/documentation/migration-guide.md#migrating-to-rdme9`, }; static description = 'List versions available in your project or get a version by SemVer (https://semver.org/).'; diff --git a/src/commands/versions/update.ts b/src/commands/versions/update.ts index 6891d4bd3..2810de69b 100644 --- a/src/commands/versions/update.ts +++ b/src/commands/versions/update.ts @@ -18,7 +18,7 @@ export default class UpdateVersionCommand extends BaseCommand Date: Fri, 4 Apr 2025 10:03:45 -0500 Subject: [PATCH 6/6] chore: format table jfc --- documentation/migration-guide.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/documentation/migration-guide.md b/documentation/migration-guide.md index 2fe121734..c275a1331 100644 --- a/documentation/migration-guide.md +++ b/documentation/migration-guide.md @@ -45,13 +45,13 @@ Please see [the `rdme@8.0.0` release notes](https://github.com/readmeio/rdme/rel ## Version Compatibility Matrix -| Feature | `v8` | `v9` | `v10` | -| ------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ----------- | ----------- | -| Actively Maintained? | ❌ | βœ… | βœ… | +| Feature | `v8` | `v9` | `v10` | +| ------------------------------------------------------------------------------------------------------------------------ | ------ | ----------- | ----------- | +| Actively Maintained? | ❌ | βœ… | βœ… | | Support for [ReadMe Refactored](https://docs.readme.com/main/docs/migration)\* | ❌ | ❌ | βœ… | -| Supports Bi-Directional Sync | ❌ | ❌ | βœ… | +| Supports Bi-Directional Sync | ❌ | ❌ | βœ… | | Support for Legacy Projects (i.e., not yet migrated to [ReadMe Refactored](https://docs.readme.com/main/docs/migration)) | βœ… | βœ… | ❌ | -| Node.js Requirements | `>=14` | `>=20.10.0` | `>=20.10.0` | +| Node.js Requirements | `>=14` | `>=20.10.0` | `>=20.10.0` | \*If you uploaded an API definition prior to migrating your project to ReadMe Refactored, any existing workflows for syncing these files that use a legacy `rdme` version (i.e., `v9` or earlier) should continue to work, even after migrating. **For new workflows, we recommend following this migration guide and upgrading to the latest version.**