docs: v10 migration guide #1107
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
kanadgupta
changed the base branch from
next
to
kanad-2024-12-05/final-v9-touchups
the oclif-generated usage docs felt messy — sort of repeating the info in the setup instructions but not really. this condenses that info and converts it to a quick start
…05/v10-migration-guide
this will make it easier to deeplink in the future
…05/v10-migration-guide
easier to deeplink in the future
kanadgupta
added a commit
that referenced
this pull request
Dec 6, 2024
## 🧰 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](#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.
kanadgupta
pushed a commit
that referenced
this pull request
Dec 6, 2024
# [9.0.0-next.36](v9.0.0-next.35...v9.0.0-next.36) (2024-12-06) * feat!: final v9 touchups ([#1106](#1106)) ([15447c5](15447c5)), closes [#1107](#1107) ### BREAKING CHANGES * `rdme openapi` is deprecated and will be replaced in `rdme@10` by a command with a simpler flag setup based on community feedback. [skip ci]
kanadgupta
pushed a commit
that referenced
this pull request
Dec 6, 2024
# [9.0.0](v8.6.6...v9.0.0) (2024-12-06) * feat!: deprecation notices for non-readme-refactored commands ([#1099](#1099)) ([732e32b](732e32b)) * feat!: drop node 18 ([#1085](#1085)) ([ebc2ac0](ebc2ac0)) * feat!: final v9 touchups ([#1106](#1106)) ([15447c5](15447c5)), closes [#1107](#1107) * feat!: oclif (take 2) ([#1068](#1068)) ([5e05f93](5e05f93)), closes [#962](#962) [#1067](#1067) [/github.com/readmeio/rdme/blob/d01d76fe3c2e4a98b4f5c415be03e589fbe3b56e/.releaserc.yml#L30](https://github.com//github.com/readmeio/rdme/blob/d01d76fe3c2e4a98b4f5c415be03e589fbe3b56e/.releaserc.yml/issues/L30) [#1067](#1067) * feat!: remove `validate`, deprecate/hide `open` ([#1072](#1072)) ([f1b46f6](f1b46f6)) * feat!: switch topic separator to space ([#1100](#1100)) ([13eb8ab](13eb8ab)) ### Bug Fixes * add better debugging for fetch failures ([a17f8da](a17f8da)) * add GITHUB_TOKEN ([e106e10](e106e10)) * attempt to use semantic-release/github instead of `gh` ([331d28b](331d28b)) * build `dist-gha/` files with every release ([f42392b](f42392b)) * bump semantic-release versions ([21efc66](21efc66)) * debug properly ([#1078](#1078)) ([5de0a4f](5de0a4f)) * **deps:** bump more deps ([#1042](#1042)) ([786a000](786a000)) * empty commit to trigger build ([51c1566](51c1566)) * empty commit to trigger build ([76efb7e](76efb7e)) * empty commit to trigger release ([3604f2a](3604f2a)) * fixed debug script ([#908](#908)) ([82c3541](82c3541)) * hide `ExperimentalWarning` ([#901](#901)) ([f9b5679](f9b5679)) * **npm:** tweak npm lifecycle scripts ([#1073](#1073)) ([35534db](35534db)) * oclif-friendly error logging ([#1080](#1080)) ([73c5f4c](73c5f4c)) * **openapi:** add spinner catch statement ([#961](#961)) ([4669b29](4669b29)) * **release:** track `dist-gha` assets properly ([b0934cb](b0934cb)) * **release:** track changes to commands doc directory ([78b6554](78b6554)) * swap out ts-node for tsx ([16f64b3](16f64b3)) * Update LICENSE for 2024 ([#963](#963)) ([23cf44b](23cf44b)) * use newest import attributes syntax ([#993](#993)) ([d76c0ae](d76c0ae)), closes [/github.com/nodejs/node/blob/main/doc/changelogs/CHANGELOG_V20.md#2023-11-22-version-20100](https://github.com//github.com/nodejs/node/blob/main/doc/changelogs/CHANGELOG_V20.md/issues/2023-11-22-version-20100) * **versions/update:** various edge cases ([#965](#965)) ([580e307](580e307)) ### chore * type fixes for tests ([#903](#903)) ([d423b4c](d423b4c)) ### Code Refactoring * remove `oas`, `swagger`, `docs:edit` ([#902](#902)) ([9107d15](9107d15)) ### Features * add `@oclif/plugin-not-found`, other cleanups ([#1074](#1074)) ([6529b03](6529b03)) * add `title` flag to `openapi:convert` ([#1071](#1071)) ([1d71f3f](1d71f3f)), closes [#1068](#1068) * convert to ESM (breaking change) ([#856](#856)) ([84b8571](84b8571)), closes [/www.stefanjudis.com/snippets/how-to-import-json-files-in-es-modules-node-js/#option-1](https://github.com//www.stefanjudis.com/snippets/how-to-import-json-files-in-es-modules-node-js//issues/option-1) [1#L228](https://github.com/1/issues/L228) * **fetch:** use undici + `ProxyAgent` ([#1000](#1000)) ([9da7132](9da7132)), closes [#999](#999) * **openapi/convert:** support openapi in convert command ([#941](#941)) ([a33bbeb](a33bbeb)) * revamped `oclif`-powered docs ([#1081](#1081)) ([8a2833b](8a2833b)) * sort when syncing by parent ([#973](#973)) ([9795840](9795840)) * support `README_API_KEY` env var ([#950](#950)) ([bcf3f18](bcf3f18)) * support node 18 and up ([#900](#900)) ([a217904](a217904)) * **test:** moving unit tests over to vitest ([#857](#857)) ([36d561b](36d561b)), closes [#870](#870) * use `actions/checkout@v4` everywhere ([#895](#895)) ([d30b71c](d30b71c)) * **versions:** flag parity with API, copy fixes ([#906](#906)) ([d424d9f](d424d9f)) ### BREAKING CHANGES * `rdme openapi` is deprecated and will be replaced in `rdme@10` by a command with a simpler flag setup based on community feedback. * deprecates commands that are not supported in ReadMe Refactored. For more information, please visit our migration guide: https://github.com/readmeio/rdme/tree/v9/documentation/migration-guide.md ## 🧬 QA & Testing Does the copy in these deprecation warnings make sense to you? Note that the links will be broken for now since we haven't tagged a proper v9 release yet, but that will be fixed once this release is out! * 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. ## 🧬 QA & Testing Do tests still pass? * dropping support for Node.js v18. The minimum required Node.js version is v20.10.0. * `rdme validate` has been removed, use `rdme openapi:validate` instead. * `rdme open` is now deprecated also updates our docs accordingly * the `rdme` GitHub Actions is now a [the `node20` JavaScript action](https://docs.github.com/en/actions/sharing-automations/creating-actions/metadata-syntax-for-github-actions#runs-for-javascript-actions) rather than [a Docker container action](https://docs.github.com/en/actions/sharing-automations/creating-actions/metadata-syntax-for-github-actions#runs-for-docker-container-actions). * `rdme` is now powered by [`oclif`](https://oclif.io/). The formatting and content of certain error messages and outputs may have changed. Please continue to only utilize exit codes to determine command successes/failures. completed tasks: - [x] a handful of tests are still failing, hoping that oclif/test#652 gets merged in) - [x] github actions dry runs are failing (but i got them working in * **versions:** this flips the `isPublic` flag to `hidden`. * removes several deprecated commands * chore: knip cleanup * chore: type fixes for tests * removes several deprecated commands * Node.js >= 18 required [skip ci]
mjcuva
approved these changes
Dec 12, 2024
erunion
approved these changes
Dec 12, 2024
kanadgupta
added a commit
that referenced
this pull request
Dec 12, 2024
## 🧰 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).
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
🧰 Changes
in #1106, i removed the v10 migration guide language so we can ship v9 properly without being blocked by the
rdme openapireplacement command status. this PR adds back that language.see #1113 for the sequencing of all of this.