Add a preference to use the latest version of a documentation - #2734
Merged
Merged
Conversation
Enabling it replaces, at boot, every enabled doc for which a newer version is available with that version, so that e.g. CMake 3.9 becomes CMake 3.12 once it is released. Only numbered versions are migrated; variants that share a name, such as Node.js 10 LTS or the Haxe targets, can't be ordered and are left alone. An empty version means the doc holds the latest version and outranks any number. saveDocs bumps the database schema, which drops the object store of the superseded doc just like disabling it manually does. Closes #744
There was a problem hiding this comment.
🟡 Changes recommended
Migration can delete a working offline version before confirming that its replacement loads successfully.
Get a fresh assessment by requesting another Copilot review.
Pull request overview
Adds an opt-in preference that migrates enabled documentation to its latest numbered version during startup.
Changes:
- Adds version comparison and migration logic.
- Adds the preference to settings and UI.
- Adds migration and version-selection tests.
File summaries
| File | Description |
|---|---|
assets/javascripts/app/app.js |
Runs and persists version migrations. |
assets/javascripts/app/settings.js |
Defines the new preference. |
assets/javascripts/models/doc.js |
Implements version detection and comparison. |
assets/javascripts/templates/pages/settings_tmpl.js |
Adds the preference checkbox. |
assets/javascripts/views/content/settings_page.js |
Exposes the preference to the template. |
test/assets/doc_version_test.js |
Tests comparison and migration behavior. |
Review details
- Files reviewed: 6/6 changed files
- Comments generated: 1
- Review effort level: Balanced
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
saveDocs bumps the database schema, which drops the object store of the doc that is disabled. Swapping before the index of the latest version is known to load left a boot that fails, e.g. an offline one, with neither the version that was installed nor the one that replaced it. The index is now loaded first and the swap is made in its success callback, so a doc that can't be fetched stays enabled and nothing is persisted.
Awaiting the index of the latest version reads better than chaining the migrations through callbacks, and bootAll can wait for them before loading the enabled docs.
There was a problem hiding this comment.
🟡 Changes recommended
Serial index loading can significantly delay startup when migrating several documentation sets.
Get a fresh assessment by requesting another Copilot review.
Review details
- Files reviewed: 6/6 changed files
- Comments generated: 1
- Review effort level: Balanced
Comment on lines
+212
to
+218
| const loaded = await new Promise((resolve) => | ||
| latest.load( | ||
| () => resolve(true), | ||
| () => resolve(false), | ||
| { readCache: true, writeCache: true }, | ||
| ), | ||
| ); |
Awaiting one index after the other delayed the boot of everyone whose docs are several releases behind. The indexes are now loaded through as many parallel requests as Docs#load makes, and a version superseding more than one enabled doc is only loaded once.
This file contains hidden or 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
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.
Closes #744.
Adds a single preference, Automatically switch to the latest version of a documentation (off by default), next to the offline download option in the General section of the preferences. It is not per documentation.
With it enabled,
App#migrateToLatestVersionsruns at boot, right aftermigrateDocsand before the docs are loaded: every enabled doc for which a newer version is available is disabled, and that newer version is enabled in its place. Enabling CMake 3.9 today therefore switches to CMake 3.10 once it is released.Details:
Doc#isNewerVersionThan), so3.9 < 3.12and9 < 10.node~10_lts("10 LTS"),gcc~7_cpp("7 CPP"), the Haxe targets,tensorflow~guide,openjdk~8_web.angular,node,webpack) and outranks any number.saveDocsbumps the database schema, soonUpgradeNeededdrops the object store of the superseded doc — its offline data is cleaned up just like when it is disabled by hand.Tested with
test/assets/doc_version_test.js(node --test test/assets/), covering the version comparison, the variants that must not migrate, and the three migration paths.