From 9ab78230aebb8ef4fe0cf3b211856fb2b55ebd5e Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Thu, 5 Dec 2024 15:54:06 -0600 Subject: [PATCH 01/14] docs: various migration guide cleanups --- documentation/migration-guide.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/documentation/migration-guide.md b/documentation/migration-guide.md index dff0ef2ec..c023a43d6 100644 --- a/documentation/migration-guide.md +++ b/documentation/migration-guide.md @@ -29,7 +29,7 @@ npx markdown-toc documentation/migration-guide.md --maxdepth 2 --bullets="-" -i > [!NOTE] -> `rdme@10` has not been released yet. If you're using ReadMe Refactored, stay tuned! +> `rdme@10` has not been released yet, so the following section is subject to change. If you're using ReadMe Refactored, stay tuned! ### Overview @@ -164,7 +164,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` @@ -176,7 +176,7 @@ If you're using the `rdme` GitHub Action, update your GitHub Actions workflow fi 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` From 0e63887e78ead0ecca7c6da38274f250bca1a013 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Thu, 5 Dec 2024 15:54:30 -0600 Subject: [PATCH 02/14] docs: v9 guidance on `rdme openapi` --- documentation/migration-guide.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/documentation/migration-guide.md b/documentation/migration-guide.md index c023a43d6..5a4aad2f2 100644 --- a/documentation/migration-guide.md +++ b/documentation/migration-guide.md @@ -173,6 +173,8 @@ If you're using the `rdme` GitHub Action, update your GitHub Actions workflow fi - `versions` - `open` + The `openapi` command will be replaced by `openapi upload` and will have 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. From 969ef6d5339a045025a009437eda0bbca0eae099 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Thu, 5 Dec 2024 15:54:37 -0600 Subject: [PATCH 03/14] docs: v10 guidance on `rdme openapi` --- documentation/migration-guide.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/documentation/migration-guide.md b/documentation/migration-guide.md index 5a4aad2f2..0654cae79 100644 --- a/documentation/migration-guide.md +++ b/documentation/migration-guide.md @@ -76,12 +76,30 @@ If you're using the `rdme` GitHub Action, update your GitHub Actions workflow fi 2. **Command Replacements** + - Replace: `openapi` → `openapi upload` (see more in step 3 below) - 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` +3. **`openapi`** changes + + If you previously uploaded API definitions to ReadMe via `rdme openapi`, the command is now `rdme openapi upload`. There are now two main updates: + + - The `--version` flag is now required. + + - Previously with `openapi`, the `--id` flag was an ObjectID that required an initial upload to ReadMe, which made it difficult to upsert API definitions and manage many at scale. With `openapi upload`, the `--id` flag is optional and the identifier is inferred from the file path or URL to your API definition. + + See the table below to get a sense of how this identifier is inferred. As long as you maintain these directory/file names and run `rdme` from the same location relative to your file, this identifier will be preserved and any updates you make to this file will be synced to the same resource in ReadMe. + + | File Path Type | Example File Path | Resulting Identifier in ReadMe | + | -------------- | ---------------------------------------- | ------------------------------ | + | Local File | `docs/api/petstore.json` | `docs-api-petstore.json` | + | URL | `https://example.com/docs/petstore.json` | `petstore.json` | + + If you wish to override this inference behavior, you can include the `--id` flag and set it to whatever identifier you'd like. + ## Migrating to `rdme@9` ### Overview From 82be197e1e4ec587725931ffbb585cc80e9c8c67 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Thu, 5 Dec 2024 15:55:04 -0600 Subject: [PATCH 04/14] feat!: deprecate `rdme openapi` --- src/commands/openapi/index.ts | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) 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' }), From cbcef0dd172c5ec50eb90f4d43a2da6e0226927c Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Thu, 5 Dec 2024 15:58:50 -0600 Subject: [PATCH 05/14] docs: remove v10 docs (for now) --- documentation/migration-guide.md | 74 ++------------------------------ 1 file changed, 4 insertions(+), 70 deletions(-) diff --git a/documentation/migration-guide.md b/documentation/migration-guide.md index 0654cae79..a453db963 100644 --- a/documentation/migration-guide.md +++ b/documentation/migration-guide.md @@ -28,78 +28,12 @@ npx markdown-toc documentation/migration-guide.md --maxdepth 2 --bullets="-" -i ## Migrating to `rdme@10` -> [!NOTE] -> `rdme@10` has not been released yet, so the following section is subject to change. 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). +> [!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! -### 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: `openapi` → `openapi upload` (see more in step 3 below) - - 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` - -3. **`openapi`** changes - - If you previously uploaded API definitions to ReadMe via `rdme openapi`, the command is now `rdme openapi upload`. There are now two main updates: - - - The `--version` flag is now required. - - - Previously with `openapi`, the `--id` flag was an ObjectID that required an initial upload to ReadMe, which made it difficult to upsert API definitions and manage many at scale. With `openapi upload`, the `--id` flag is optional and the identifier is inferred from the file path or URL to your API definition. - - See the table below to get a sense of how this identifier is inferred. As long as you maintain these directory/file names and run `rdme` from the same location relative to your file, this identifier will be preserved and any updates you make to this file will be synced to the same resource in ReadMe. - - | File Path Type | Example File Path | Resulting Identifier in ReadMe | - | -------------- | ---------------------------------------- | ------------------------------ | - | Local File | `docs/api/petstore.json` | `docs-api-petstore.json` | - | URL | `https://example.com/docs/petstore.json` | `petstore.json` | - - If you wish to override this inference behavior, you can include the `--id` flag and set it to whatever identifier you'd like. - ## Migrating to `rdme@9` ### Overview From 6b783fc7371f55a77f65f75088c3f5c650aa5965 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Thu, 5 Dec 2024 16:01:21 -0600 Subject: [PATCH 06/14] docs: actually don't even name what the command is called --- documentation/migration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/migration-guide.md b/documentation/migration-guide.md index a453db963..b7ca07581 100644 --- a/documentation/migration-guide.md +++ b/documentation/migration-guide.md @@ -125,7 +125,7 @@ If you're using the `rdme` GitHub Action, update your GitHub Actions workflow fi - `versions` - `open` - The `openapi` command will be replaced by `openapi upload` and will have a simpler flag setup based on community feedback. + 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** From f936e7b6bdc0baffdff6f633fa0530b83d7c7837 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Thu, 5 Dec 2024 16:05:26 -0600 Subject: [PATCH 07/14] Revert "docs: actually don't even name what the command is called" This reverts commit 6b783fc7371f55a77f65f75088c3f5c650aa5965. --- documentation/migration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/migration-guide.md b/documentation/migration-guide.md index b7ca07581..a453db963 100644 --- a/documentation/migration-guide.md +++ b/documentation/migration-guide.md @@ -125,7 +125,7 @@ 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. + The `openapi` command will be replaced by `openapi upload` and will have a simpler flag setup based on community feedback. 6. **Verify any scripts that utilize raw CLI outputs** From 1b8a10d8bebd0faed89814d6342655c6c44fbe31 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Thu, 5 Dec 2024 16:05:29 -0600 Subject: [PATCH 08/14] Revert "docs: remove v10 docs (for now)" This reverts commit cbcef0dd172c5ec50eb90f4d43a2da6e0226927c. --- documentation/migration-guide.md | 74 ++++++++++++++++++++++++++++++-- 1 file changed, 70 insertions(+), 4 deletions(-) diff --git a/documentation/migration-guide.md b/documentation/migration-guide.md index a453db963..0654cae79 100644 --- a/documentation/migration-guide.md +++ b/documentation/migration-guide.md @@ -28,12 +28,78 @@ npx markdown-toc documentation/migration-guide.md --maxdepth 2 --bullets="-" -i ## Migrating to `rdme@10` -> [!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! +> [!NOTE] +> `rdme@10` has not been released yet, so the following section is subject to change. 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: `openapi` → `openapi upload` (see more in step 3 below) + - 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` + +3. **`openapi`** changes + + If you previously uploaded API definitions to ReadMe via `rdme openapi`, the command is now `rdme openapi upload`. There are now two main updates: + + - The `--version` flag is now required. + + - Previously with `openapi`, the `--id` flag was an ObjectID that required an initial upload to ReadMe, which made it difficult to upsert API definitions and manage many at scale. With `openapi upload`, the `--id` flag is optional and the identifier is inferred from the file path or URL to your API definition. + + See the table below to get a sense of how this identifier is inferred. As long as you maintain these directory/file names and run `rdme` from the same location relative to your file, this identifier will be preserved and any updates you make to this file will be synced to the same resource in ReadMe. + + | File Path Type | Example File Path | Resulting Identifier in ReadMe | + | -------------- | ---------------------------------------- | ------------------------------ | + | Local File | `docs/api/petstore.json` | `docs-api-petstore.json` | + | URL | `https://example.com/docs/petstore.json` | `petstore.json` | + + If you wish to override this inference behavior, you can include the `--id` flag and set it to whatever identifier you'd like. + ## Migrating to `rdme@9` ### Overview From 826fecaf957595f420a6ee319c54a183e9c5f40a Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Fri, 6 Dec 2024 09:17:52 -0600 Subject: [PATCH 09/14] docs: add more descriptions for the key and version flags --- 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 ++++++++++++++++++++++++--- src/lib/flags.ts | 10 ++++-- 7 files changed, 158 insertions(+), 23 deletions(-) diff --git a/documentation/commands/categories.md b/documentation/commands/categories.md index 70021b722..85e9355de 100644 --- a/documentation/commands/categories.md +++ b/documentation/commands/categories.md @@ -15,9 +15,10 @@ USAGE $ rdme categories --key [--version ] FLAGS - --key= (required) ReadMe Project API key - --version= Project version. If running command in a CI environment and this option is not passed, the main - project version will be used. + --key= (required) 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 + --version= ReadMe project version DESCRIPTION Get all categories in your ReadMe project. @@ -26,6 +27,19 @@ EXAMPLES Get all categories associated to your project version: $ rdme categories --version={project-version} + +FLAG DESCRIPTIONS + --key= + + 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 + + ReadMe project API key + + --version= ReadMe project version + + 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 ``` ## `rdme categories create TITLE` @@ -42,11 +56,12 @@ ARGUMENTS FLAGS --categoryType=