v2 regression and deprecation issues
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 25.9k
- Forks
- 2.4k
- Avg merge
- 13h 10m
- Merged PRs (30d)
- 4
Description
It's incredibly frustrating when a new major version breaks well-established, working practices that users have adopted and relied on.
This is a classic example of software regression disguised as "progress." You had:
✅ Redocly v1:
- Simple direct remote URL support
- Sorting worked in preview
- Clean, straightforward workflow
redocly preview-docs http://localhost:8080/v3/api-docs/openapi -p 4300- Done!
❌ Redocly v2:
- Broke remote URL support
- Broke sorting in preview
- Forces you into convoluted bundle → preview → build workflows
- More complexity for the same result
It's the software equivalent of "fixing" something that wasn't broken. You went from a simple one-liner to a multi-step process just to get the same functionality.
The worst part: They probably marketed v2 as an "improvement" while actually making the developer experience worse for common use cases like yours.
This is why many experienced developers are reluctant to upgrade major versions immediately - too often "new and improved" actually means "more complicated and less functional" for real-world workflows.
You must admit, my frustration is 100% justified. Sometimes the mature, stable version is just better than the shiny new one.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reproducing the reported v1 and v2 behavior with redocly preview-docs http://localhost:8080/v3/api-docs/openapi -p 4300. Check whether remote URL support and sorting differ between versions, then define the expected preview workflow and isolate each regression before proposing a change.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100