docs: Rewrite Settings and Workspaces documentation#9065
Merged
Conversation
- Add 'Schema validation behavior' subsection explaining lazy validation, no-op when no schema is registered, and type mismatch error behavior - Add IModelHost.onAfterStartup example for schema registration - Add 'Dictionary structure recommendations' subsection with naming conventions and organization guidance - Expand 'Settings priorities' section with practical org/iTwin workflow and wire in Settings.addITwinDictionary / Settings.dropITwinDictionary extracts that were previously unused - Add 'Persisted vs session-only dictionaries' comparison table under 'iModel settings' explaining addDictionary vs saveSettingDictionary - Add JSDoc cross-references between Settings.addDictionary and IModelDb.saveSettingDictionary Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
hl662
force-pushed
the
nam/settings-workspace-docs
branch
from
4f17b0b to
de4596b
Compare
hl662
changed the title
…pace resources - Add WorkspacesAndSettings.md: high-level overview with 4 Mermaid diagrams (architecture, runtime resolution sequence, priority stack, container discovery) reflecting actual shipped APIs (explicit containerId/priority, SettingsEditor for discovery, no CatalogDb) - Add Settings.md: full Settings deep-dive (schemas, dictionaries, priorities, iModel settings, SettingsDb) with priority-stack Mermaid diagram; includes⚠️ caution on iModel settings (saveSettingDictionary) advising SettingsDb for new work - Rewrite Workspace.md: WorkspaceDb-only deep-dive with container hierarchy Mermaid diagram and links to overview and Settings.md - Add JSDoc caution to IModelDb.saveSettingDictionary and deleteSettingDictionary pointing users to SettingsDb as the preferred approach - Update cross-references: Preferences.md, NextVersion.md (#settingsdb link), and backend/index.md (new Workspaces and Settings section) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Replace bare `$backend` link target with the correct relative path `./Workspace.md`. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Two issues broke all affected diagrams: 1. `"` HTML entities decoded to `"` by the doc pipeline before Mermaid runs, causing label parsing failures when a double-quoted label [\...\] contained decoded double quotes inside it. Fix: use single quotes in those label strings. 2. `\n` escape sequences in node labels are not valid Mermaid syntax. Fix: replace with `<br/>` which Mermaid supports for line breaks. Files affected: WorkspacesAndSettings.md, Settings.md, Workspace.md Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…agram Multi-line subgraph titles using <br/> cause Mermaid to missize the header area, making the box border overlap the title text. Fix by using single-line subgraph titles. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Title 'CloudSqlite (shared infrastructure)' was too wide, causing the subgraph border to clip through the label text. Shortened to just 'CloudSqlite'. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Merged
…ace-docs # Conflicts: # docs/changehistory/NextVersion.md # docs/learning/backend/Workspace.md
- Settings.md: consolidated all settings content (schemas, dictionaries, priorities, iTwin settings, iModel settings, SettingsDb) as single source of truth. Added iTwin settings section and expanded iModel settings with override/reference/pin subsections. - Workspace.md: trimmed from 348 to 138 lines. Removed all settings content. Added 'Choosing the right workspace' decision guide near top with scope table (appWorkspace vs getITwinWorkspace vs IModelDb.workspace). - WorkspacesAndSettings.md: added three-workspace scope table for the app/iTwin/iModel model introduced in PR #9116. - Fixed cross-references: 5.8.0.md settingsdb link now points to Settings.md, NextVersion.md links to both Settings and Workspace docs. - Verified all 28 code example includes appear exactly once (zero duplicates across files). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Hybrid SettingsDb/WorkspaceDb framing in Settings.md iTwin section - Note in overview that diagram simplifies org/iTwin into one level - Orientation block before iTwin settings (session-only vs persisted vs SettingsDb) - Workspace.md title now 'Workspace Resources (WorkspaceDb)' - Added plain-English heuristic to decision guide table - Qualified 'workspace' as 'workspace scope' in key Settings.md passages - Renamed '## Settings' to '## What is a setting?' - Fixed awkward GeographicCRS link text - Replaced 'Learn more' with 'Recommended reading order' Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Create 5 extract markers referenced by docs/learning/backend/Settings.md that were causing CI build failures: - SettingsDb.discoverContainers - SettingsDb.findContainers - SettingsDb.createLocal - SettingsDb.updateSetting - SettingsDb.getSettings Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
![github-code-quality[bot]](https://avatars.githubusercontent.com/u/9919?s=60&v=4){kind=small}
Replace fictional API names with actual public API names: - SettingsEditor.* → WorkspaceEditor.* - EditableSettingsCloudContainer.* → EditableWorkspaceContainer.* - EditableSettingsDb.* → EditableWorkspaceDb.* - SettingsDb.getSetting/getSettings → WorkspaceDb.getString - Workspace.getSettingsDb → Workspace.loadSettingsDictionary - GetSettingsDbArgs.priority → WorkspaceDbSettingsProps.priority Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Resolve conflict in IModelDb.ts by keeping both the SettingsDb recommendation notes from our branch and the @deprecated tags from master directing users to EditTxn. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
johnnyd710
reviewed
Apr 8, 2026
SettingsDb is an @internal type alias — it should not be exposed as a user-facing concept. Replace all mentions with 'settings container' (a WorkspaceDb in a container tagged containerType: 'settings'). Also addresses PR review feedback: - Fix unused variable in snippet (#1) - Fix inheritance claim in WorkspacesAndSettings.md (#2) - Remove write lock claim and soften caution (#6, #7) - Fix inheritance claim in Settings.md (#8) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Update all 5 extract marker IDs and their corresponding [[include:]] references in Settings.md to use SettingsContainer prefix instead of SettingsDb, completing the terminology cleanup. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Remove duplicate WorkspaceDb.getString listing (there is only one getString method; no 'get all settings' method exists on WorkspaceDb) - Fix createNewCloudContainer claim: containerType must be explicitly specified as 'settings' (default is 'workspace', not auto-tagged) - Clarify write lock note: locks are independent because they are separate cloud containers, not because of a special settings lock Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
johnnyd710
reviewed
Apr 13, 2026
- Remove misleading 'Prefer SettingsDb' notes from IModelDb TSDoc - Update Settings.ts class-level doc to reference EditTxn methods - Fix Workspace.md table: IModelDb.workspace does not auto-include iTwin settings - Trim WorkspacesAndSettings.md: lead with getITwinWorkspace, remove redundancy - Add workspace.close() requirement note in Settings.md - Add consume/load code for referencing iTwin settings from an iModel - Clarify saveSettingDictionary vs WorkspaceEditor scope in Settings.md Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…clarity
- Replace IModelDb.saveSettingDictionary/deleteSettingDictionary refs with
EditTxn equivalents (via withEditTxn) in Settings.md prose and inline code
- Add close() inside extract boundaries for GetITwinWorkspace,
ReadITwinSettings, SaveTreeDbsToITwin, SaveITwinSettingsReferenceInIModel
- Add ReadITwinSettings extract with getNumber usage
- Fix wrong comment in QuerySettingDictionary extract ({min:8,max:10} -> {min:6,max:8})
- Add scope bridging note in Workspace.md explaining iModel.workspace
does not auto-inherit iTwin settings
- Add containerType labels to mermaid diagram in WorkspacesAndSettings.md
- Add type annotation to inline getSetting<WorkspaceDbSettingsProps>
- Strengthen addDictionary session-only note in priority section
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
hl662
commented
Apr 15, 2026
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
hl662
changed the title
khanaffan
reviewed
Apr 15, 2026
Clarify that getITwinWorkspace is independent from appWorkspace/IModelDb.workspace priority stack, addressing reviewer feedback on conflicting table description. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The #settingsdb anchor no longer exists in Settings.md after the docs rewrite. Updated to point to #settings-containers instead. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…n/itwinjs-core into nam/settings-workspace-docs
johnnyd710
reviewed
Apr 17, 2026
johnnyd710
left a comment
johnnyd710
left a comment
Contributor
There was a problem hiding this comment.
I found the documentation was easier to understand and flowed better when there was one document that went through a single user-story (LandscapePro). It only brought technical details when necessary. In general I find examples easier than concepts/diagrams but maybe that's just me
Remove container types section, mermaid diagrams, container discovery. Fix scope/priority wording and bootstrapping explanation. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Create WorkspaceTutorial.md with 11-step LandscapePro narrative - Add LandscapePro-specific iTwin persistence snippets - Fix pre-existing SettingsDb test failure (missing containerType, improper db lifecycle with getEditableDb) - Update overview reading order with tutorial callout Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The SaveITwinSettingsReferenceInIModel snippet now clearly saves a floating reference (no version field — follows latest). The VersionAndPinITwinSettings snippet resolves each WorkspaceDb to its current version and bakes that exact version into the saved reference, locking the iModel to that snapshot. Updated tutorial Step 11 prose to explain the distinction and how to unpin. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
johnnyd710
reviewed
Apr 21, 2026
… snippets, simplify pin - Remove 'How settings and resources connect' section (redundant) - Remove mermaid priority diagram (inaccurate, low value) - Remove 'Persisted vs session-only' subsection (repetitive) - Extract DeleteIModelSettingDictionary and LoadITwinSettingsFromIModel snippets - Simplify version pin snippet to use literal version string - Move admin workflows under 'Advanced: managing settings containers' - Fix mermaid diagram to include iTwin workspace scope Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Explain the read/write split for iTwin settings containers, document the single auto-discoverable container assumption, and fix the SettingsPriority links in the tutorial. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Incorporate follow-up review feedback: add migration guidance for deprecated IModelDb settings APIs, improve the Settings introduction and startup guidance, and tighten overview wording. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
ben-polinsky
approved these changes
Apr 22, 2026
johnnyd710
approved these changes
Apr 22, 2026
Accept the last outstanding wording suggestion in Settings.md and update the PR description to call out the new one-page tutorial. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
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
5 participants
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.
Rewrite and restructure Workspace & Settings learning docs
Rewrites the three linked learning docs (
WorkspacesAndSettings.md,Workspace.md,Settings.md) and adds a one-page tutorial (WorkspaceTutorial.md) so the whole settings/workspace flow is simpler, beginner-friendly, and factually accurate.Goals
Key changes
iModel.workspaceauto-includes iTwin settings, added scope-bridging guidanceIModelDb.saveSettingDictionary/deleteSettingDictionaryguidance withEditTxnequivalents, clarified session-only vs persisted dictionaries, addedclose()notes, and documented the default single-container iTwin settings workflowclose()calls inside extract boundaries, restored accidentally removed extract, and tightened the advanced settings-container guidanceSettingsclass-level doc andaddDictionaryto reference current APIsValidation
Targeted verification:
getITwinWorkspace/saveSettingDictionarybehaviorSettingsPriority.*links in the tutorial and verified the remaining touched markdown passesgit diff --checkKnown baseline issues: