From 15447c52b414b97345b33ff7e17007fdd2fde106 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Fri, 6 Dec 2024 09:38:41 -0600 Subject: [PATCH] feat!: final v9 touchups (#1106) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 🧰 Changes a few final touchups before we ship v9 🚀 - [x] adds a deprecation notice to `rdme openapi` - [x] removes the usage section from our docs in favor of a quick start - [x] improves the documentation for our `--key` and `--version` flags - [x] removes all `v10` migration guide language for now and adds a placeholder. i have a separate PR ([#1107](https://github.com/readmeio/rdme/pull/1107)) that adds that language back when we're ready. i figured i'd chunk this out so we can ship v9 without having to finalize the new `rdme openapi` command replacement. ## 🧬 QA & Testing Do these doc changes look sound? --- BREAKING CHANGE: `rdme openapi` is deprecated and will be replaced in `rdme@10` by a command with a simpler flag setup based on community feedback. --- README.md | 63 ++++++++++++-------------- documentation/commands/categories.md | 40 ++++++++++++++--- documentation/commands/changelogs.md | 12 ++++- documentation/commands/custompages.md | 12 ++++- documentation/commands/docs.md | 40 ++++++++++++++--- documentation/commands/openapi.md | 19 ++++++-- documentation/commands/versions.md | 48 ++++++++++++++++++-- documentation/migration-guide.md | 64 ++++----------------------- src/commands/openapi/index.ts | 8 +++- src/lib/flags.ts | 10 ++++- 10 files changed, 202 insertions(+), 114 deletions(-) diff --git a/README.md b/README.md index a41b8328f..a3ed86942 100644 --- a/README.md +++ b/README.md @@ -37,13 +37,39 @@ npm run build && npm run build:docs * [Table of Contents](#table-of-contents) +* [Quick Start](#quick-start) * [CLI Configuration](#cli-configuration) * [GitHub Actions Configuration](#github-actions-configuration) -* [Usage](#usage) * [Command Topics](#command-topics) +# Quick Start + +Install the CLI ([see here for more setup options](#setup)): + +```sh +npm install -g rdme +``` + +Validate an OpenAPI file in your working directory or any subdirectories ([see here for all command topics](#command-topics)): + +```sh +rdme openapi validate +``` + +Every command has a help page, which you can access in [our docs](./documentation/commands) or via the CLI: + +```sh +rdme openapi validate --help +``` + +To view the current version of `rdme` (helpful for troubleshooting and bug reports): + +```sh +rdme --version +``` + # CLI Configuration ## Setup @@ -119,7 +145,7 @@ rdme openapi > [!NOTE] > For a full GitHub Workflow file example and additional information on GitHub Actions usage, check out [our docs](https://docs.readme.com/docs/rdme#github-actions-usage). -For usage in [GitHub Actions](https://docs.github.com/actions), you can create a new GitHub Actions workflow file by including the `--github` flag with the command you wish to run in GitHub Actions. For example: +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 @@ -129,39 +155,6 @@ This will run through the `openapi` command, ask you a few quick questions, and You can see examples featuring the latest version in [our docs](https://docs.readme.com/docs/rdme#github-actions-examples). We recommend [configuring Dependabot to keep your actions up-to-date](https://docs.github.com/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot). -# Usage - - - - - -```sh-session -$ npm install -g rdme -$ rdme COMMAND -running command... -$ rdme (--version) -rdme/9.0.0-next.35 linux-x64 node-v20.18.1 -$ rdme --help [COMMAND] -USAGE - $ rdme COMMAND -... -``` - - - -## Common `rdme` Options - -- `--key `: The API key associated with your ReadMe project. Note that most of the commands below require API key authentication, even though the `--key` flag is omitted from the examples. See the [Authentication](#authentication) section above for more information. -- `--version `: Your project version. See [our docs](https://docs.readme.com/docs/versions) for more information. - -> [!NOTE] -> `rdme@10` has not been released yet. If you're using ReadMe Refactored, stay tuned! +> [!WARNING] +> `rdme@10` has not been released yet, so this section is still under construction. +> +> [Please verify that you're looking at the latest docs for v9](https://github.com/readmeio/rdme/tree/v9/documentation/migration-guide.md). If you're using ReadMe Refactored, stay tuned! -### Overview - -A [bi-directional syncing](https://docs.readme.com/main/docs/bi-directional-sync) workflow with [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored) mostly eliminates the need for a tool like `rdme`. For syncing Markdown files, syncing API definitions, and managing project hierarchy (e.g., project versions and categories) with ReadMe Refactored, you'll want to set up bi-directional syncing. - -`rdme@10` is recommended for the following use cases: - -- Syncing your API definition (generated via a build process and not tracked via Git) to your ReadMe Refactored-enabled project -- Syncing Markdown files to the Changelog for your ReadMe Refactored-enabled project - - -> [!NOTE] -> `rdme@10` only works with ReadMe projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored). If you are not yet using ReadMe Refactored, [you'll want to use `rdme@9`](#migrating-to-rdme9). - - -### Upgrading to `v10` - -#### Step 1: Upgrade via `npm` - -To install this version of the `rdme` CLI globally, run the following command: - -```sh -npm install -g rdme@10 -``` - -More installation options can be found in [our docs](https://github.com/readmeio/rdme/tree/v10?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 `v10` reference like so: - -```yaml -- uses: readmeio/rdme@v10 - with: - rdme: openapi validate petstore.json -``` - -#### Step 3: Address Breaking Changes - -1. **Enable Bi-Directional Syncing** _(recommended)_ - - We recommend setting up [bi-directional syncing](https://docs.readme.com/main/docs/bi-directional-sync) for managing your Markdown files, API definitions and project hierarchy. - -2. **Command Replacements** - - - Replace: `categories` → use [Git-based workflow](https://docs.readme.com/main/docs/bi-directional-sync) - - Replace: `custompages` → use [Git-based workflow](https://docs.readme.com/main/docs/bi-directional-sync) - - Replace: `docs` (and its `guides` alias) → use [Git-based workflow](https://docs.readme.com/main/docs/bi-directional-sync) - - Replace: `versions` → use [Git-based workflow](https://docs.readme.com/main/docs/bi-directional-sync) - - Remove: `open` - ## Migrating to `rdme@9` ### Overview @@ -128,7 +80,7 @@ If you're using the `rdme` GitHub Action, update your GitHub Actions workflow fi rdme: openapi validate petstore.json ``` -#### Step 3: Address Breaking Changes +#### Step 3: Address `v9` Breaking Changes 1. **Verify your runtime** @@ -164,7 +116,7 @@ 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 future releases: + The following commands (and their subcommands) will be removed in `rdme@10`: - `categories` - `changelogs` @@ -173,10 +125,12 @@ If you're using the `rdme` GitHub Action, update your GitHub Actions workflow fi - `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 `rdme openapi`, we recommend relying on CLI exit codes in your workflows rather than raw command outputs. + - 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` diff --git a/src/commands/openapi/index.ts b/src/commands/openapi/index.ts index 44947f3a3..3d12fabe7 100644 --- a/src/commands/openapi/index.ts +++ b/src/commands/openapi/index.ts @@ -22,7 +22,13 @@ export default class OpenAPICommand extends BaseCommand { "Locates your API definition (if you don't supply one), validates it, and then syncs it to your API reference on ReadMe."; // needed for unit tests, even though we also specify this in src/index.ts - static id = 'openapi'; + static id = 'openapi' as const; + + 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`, + }; static args = { spec: Args.string({ description: 'A file/URL to your API definition' }), diff --git a/src/lib/flags.ts b/src/lib/flags.ts index 16c355419..b3cf58336 100644 --- a/src/lib/flags.ts +++ b/src/lib/flags.ts @@ -8,7 +8,12 @@ export const githubFlag = Flags.boolean({ description: 'Create a new GitHub Acti /** * Used in any command where `key` is a `flag. */ -export const keyFlag = Flags.string({ description: 'ReadMe Project API key', required: true }); +export const keyFlag = Flags.string({ + description: 'ReadMe project API key', + required: true, + summary: + 'An API key for your ReadMe project. Note that API authentication is required despite being omitted from the example usage. See our docs for more information: https://github.com/readmeio/rdme/tree/v9#authentication', +}); /** * Used in the `openapi` family of commands where `title` is an option. @@ -22,7 +27,8 @@ export const titleFlag = Flags.string({ */ export const versionFlag = Flags.string({ description: - 'Project version. If running command in a CI environment and this option is not passed, the main project version will be used.', + 'Your ReadMe project version. If running command in a CI environment and this option is not passed, the main project version will be used. See our docs for more information: https://docs.readme.com/main/docs/versions', + summary: 'ReadMe project version', }); /**