docs: warning callouts on outdated pages #1163
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
erunion
approved these changes
Feb 1, 2025
kanadgupta
deleted the
kanad-2025-01-31/deprecation-warnings-in-main-rdme-page
branch
kanadgupta
added a commit
that referenced
this pull request
Feb 3, 2025
## 🧰 Changes adds temporary "this is outdated" callouts to the pages we sync to our guides, and moves those pages into their own respective `legacy/` directory. we'll add new docs to backfill this info (ideally with better separation of concerns) sometime in the not-too-distant future.
|
🎉 This PR is included in version 10.1.2-next.1 🎉 The release is available on:
Your semantic-release bot 📦🚀 |
kanadgupta
added a commit
that referenced
this pull request
Feb 4, 2025
| 🚥 Resolves RM-11796, RM-11797 | | :------------------- | ## 🧰 Changes ### 🚧 outstanding work - [x] core command + helper logic - [x] tests - [x] loading states - [x] complete error messages - [x] docs - [x] migration guide (see #1161) - [x] callouts in `documentation/rdme.md` (see #1163) ### 🔜 to be addressed in follow-up PRs - [ ] safeguards for users that use bidirectional syncing (ticketed in RM-11883 and RM-11901) - [ ] updating the v9 migration guide + deprecation warnings (ticketed in RM-11902) ### things to call out - on a high level, we're mostly matching the functionality of v9's `rdme docs` in that we're just taking markdown files and sending its contents as a body payload to the ReadMe API. inferring page hierarchy from directory/file structure is out of scope for this work. - one big change from `rdme@9` is that we now validate page front matter against the schemas from our OAS before making any API requests and prompt the user to migrate any frontmatter that we recognize as legacy APIv1 attributes. i'm open to reevaluating this paradigm, but i think it'll be helpful for folks migrating. as an interim escape hatch, this command has a hidden `--skip-validation` flag, just in case. - our API expects category and parent page URIs to be a full URI (e.g., `/versions/stable/categories/guides/some-uri`), but that's a bit arduous for `rdme` users since most of the URI can be inferred from the `rdme` command context. as a result, `rdme` will automatically expand any category/parent URIs that don't match that pattern (i.e., a category URI front matter value of `some-uri` will be changed to `/versions/stable/categories/guides/some-uri` before we make the `POST`/`PATCH` request) - the vast majority of this diff is tests + fixtures + our OAS. the three files of note are: - `src/lib/syncPagePath.ts` - `src/lib/frontmatter.ts` - `src/commands/docs/upload.ts` - i've tried to build this in a testable and robust way where we can easily add support for reference pages, custom pages, etc. in the future - `PATCH` requests to our API (i.e., for making updates to guide pages) that include `slug` in the body payload will always rename the page. so if you have a slug called `some-page` and your body payload contains `some-page`, the API will change your slug to `some-page-1`. this is most likely unexpected behavior for users of `rdme`, so i'm **always** removing the slug from the body payload in favor of using the URL instead. the trade-off is that page renaming isn't really a thing via `rdme`, but that's why we support bidirectional syncing, right? ## 🧬 QA & Testing we're at nearly 100% test coverage with this work 📈 to QA it yourself, check out this branch and run the following: ```sh # install + set up npm ci npm run build ``` ```sh # grab an API key from a readme-refactored-enabled project and pop it at the end of this command: bin/run.js docs upload __tests__/__fixtures__/docs/mixed-docs --key <key> ```
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
adds temporary "this is outdated" callouts to the pages we sync to our guides, and moves those pages into their own respective
legacy/directory.we'll add new docs to backfill this info (ideally with better separation of concerns) sometime in the not-too-distant future.