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 c289c4cd3..c275a1331 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 @@ -34,114 +34,24 @@ 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/welcome-to-readme-refactored). 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) will be removed in `rdme@10`: - - - `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. - -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). ## Version Compatibility Matrix -| Feature | `v8` | `v9` | `v10` | -| ------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ----------- | ----------- | -| Actively Maintained? | ❌ | βœ… | βœ… | -| Support for [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored)\* | ❌ | ❌ | βœ… | -| 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)) | βœ… | βœ… | ❌ | -| Node.js Requirements | `>=14` | `>=20.10.0` | `>=20.10.0` | +| Feature | `v8` | `v9` | `v10` | +| ------------------------------------------------------------------------------------------------------------------------ | ------ | ----------- | ----------- | +| Actively Maintained? | ❌ | βœ… | βœ… | +| 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/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.** 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 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.\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