Build and publish v4 lib/ and themes/ folders for backwards compatibility while users transition to v5.
#2667
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
| npm publish --tag "$RELEASE_TAG" | ||
| fi | ||
|
|
||
| npm run clean:v4 # clean up legacy v4 build files |
There was a problem hiding this comment.
@sy-records now that release.sh is updated, can you try this out with a --dry run to verify it works? The dry run output will show which files would be published (without publishing).
There was a problem hiding this comment.
Pull request overview
This PR adds build infrastructure to maintain v4 backwards compatibility in the v5 release by building and publishing the legacy lib/ and themes/ folders alongside the new v5 dist/ folder. This prevents existing v4 sites using unversioned CDN URLs from breaking when v5 is published.
Changes:
- Added v4 build and clean scripts to package.json
- Integrated v4 build/clean into the release process
- Added CI tests to verify v4 build and cleanup work correctly
Reviewed changes
Copilot reviewed 4 out of 5 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| package.json | Adds build:v4, build:v4:deprecate, and clean:v4 scripts; includes lib/ and themes/ in published files |
| build/release.sh | Integrates v4 build after tests and v4 cleanup after npm publish |
| .gitignore | Adds lib/ and themes/ to ignored files |
| .github/workflows/test.yml | Adds CI test to verify v4 build creates expected files and cleanup removes them |
| docs/quickstart.md | Updates versioning documentation with improved formatting and additional semver examples |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
package.json
Outdated
| "build:emoji": "node ./build/emoji.js", | ||
| "build:js": "rollup -c", | ||
| "build:types": "tsc", | ||
| "build:v4": "git checkout v4 && npm clean-install && git co docs/emoji.md src/core/render/emoji-data.js && rimraf packages/ && git checkout - && npm clean-install && npm run build:v4:deprecate -- lib/docsify.js && npm run build:v4:deprecate -- lib/docsify.min.js", |
There was a problem hiding this comment.
@sy-records note here, it relies on a new v4 tag. If we update v4 for any reason (f.e. a security patch of some really annoying and compelling bug without workaround that a user has and they can't migrate to 5.0 yet), then we should also update the v4 tag to point to the latest v4 version. That way this script will work without modification, and will simply build the latest v4 version.
…lity while users transition to v5. - add a script to build the legacy v4 lib/ and themes/ folders - append deprecation console warnings to the v4 JS files during the v4 build - add a script to clean v4 build outputs - hook the v4 build/clean scripts into the release.sh script - test the v4 build and clean in CI
| "build:emoji": "node ./build/emoji.js", | ||
| "build:js": "rollup -c", | ||
| "build:types": "tsc", | ||
| "build:v4": "git checkout v4 && npm clean-install && git checkout docs/emoji.md src/core/render/emoji-data.js && rimraf packages/ && git checkout - && npm clean-install && npm run build:v4:deprecate -- lib/docsify.js && npm run build:v4:deprecate -- lib/docsify.min.js", |
There was a problem hiding this comment.
If version 5.0.0 is released, will the version in package.json update after checking out v4?
Summary
Changes:
build:v4script to build the legacy v4 lib/ and themes/ foldersclean:v4script to clean v4 build outputsbuild/release.shscriptThis makes is so that when we publish 5.0, the published files will include the legacy v4
lib/andthemes/folders. This will prevent websites that are still using unversioned URLs (such ashttps://unpkg.com/docsify/lib/docsify.js, due to v4 docs and CLI instructing people to use unversioned URLs and thedocsify-cliinitializing projects with unversioned URLs) from breaking when we release 5.0. Existing v4 websites will simply continue to load the v4 files as if nothing changed despite that the library version will be v5 instead of v4, while new 5.0 users will opt into the new paths in thedist/folder, will be instructed to use versioned URLs in our docs, and will have projects initialized bydocsify-cliusing versioned URLs by default.Related issue, if any:
What kind of change does this PR introduce?
For any code change,
Does this PR introduce a breaking change?
Tested in the following browsers: