Skip to content

Latest commit

 

History

History
209 lines (133 loc) · 10.1 KB

migration-guide.md

File metadata and controls

209 lines (133 loc) · 10.1 KB
Raw

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.

  1. If your project is using ReadMe Refactored, use rdme@v10 and beyond.
  2. If your project is not yet using ReadMe Refactored, use rdme@v9. 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

Migrating to rdme@10

Overview

A bi-directional syncing workflow with 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. If you are not yet using ReadMe Refactored, you'll want to use rdme@9.

Upgrading to v10

Step 1: Upgrade via npm

To install this version of the rdme CLI globally, run the following command:

npm install -g rdme@10

More installation options can be found in our docs.

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:

- uses: readmeio/rdme@v10
  with:
    rdme: openapi validate petstore.json

Step 3: Address v10 Breaking Changes

  1. Enable Bi-Directional Syncing (recommended)

    We recommend setting up bi-directional syncing for managing your Markdown files, API definitions and project hierarchy.

  2. Command Replacements

  3. openapi has been replaced by openapi upload

    If you previously uploaded API definitions to ReadMe via rdme openapi, the command is now rdme openapi upload. There are now two main updates:

    • There is no prompt to select your ReadMe project version if you omit the --version flag. It now defaults to stable (i.e., your main ReadMe project version).

    • 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 has been renamed to --slug and is now optional. The slug (i.e., the unique identifier for your API definition resource in ReadMe) is inferred from the file path or URL to your API definition.

    Read more in the openapi upload command docs.

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

  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
    • 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. If you are using ReadMe Refactored, you'll want to use rdme@10.

Upgrading to v9

Step 1: Upgrade via npm

To install this version of the rdme CLI globally, run the following command:

npm install -g rdme@9

More installation options can be found in our docs.

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:

- 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

  4. Version flag updates

    The CLI flags on the versions create and versions update commands now maintain parity with our API flags. The --isPublic flag has been removed in favor of a new flag called --hidden, which is the inverse of --isPublic.

    Before

    rdme versions:create 1.0.1 --isPublic true

    After

    rdme versions create 1.0.1 --hidden false

  5. Deprecated commands

    The following commands (and their subcommands) will be removed in rdme@10:

    • categories
    • changelogs
    • custompages
    • docs (and its guides alias)
    • 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, 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 [email protected] release notes.

Version Compatibility Matrix

Feature v8 v9 v10
Actively Maintained? ❌ ✅ ✅
Support for ReadMe Refactored ❌ ❌ ✅
Supports Bi-Directional Sync ❌ ❌ ✅
Support for Legacy Projects (i.e., not yet migrated to ReadMe Refactored) ✅ ✅ ❌
Node.js Requirements >=14 >=20.10.0 >=20.10.0

Need Help?

If you notice any issues or disruptions to your workflow during migration, we're here to help! Feel free to...