Fix event-queue and config-override docs; fill capability and attribute-tag gaps - #29
Merged
Merged
Conversation
…te-tag gaps Article-level pass over the 2024.1-patch/2025.1 window. Two of these are correctness bugs that would have made a reader's configuration silently not work; the rest are gaps where What's New listed a feature but no article reflected it. Corrections: - cloudshell-event-queue.md: the Supported Events list and the ServerEventsWhiteList.csv example used .NET class names (UserCreatedEvent, LoginEvent). The whitelist and the published message's EventType field both use the registry's friendly names (UserCreated, Login) - see PublishableEventsList.cs. Every name in the documented example would have been rejected with "Could not subscribe to event", and a file containing only unrecognized names publishes nothing at all. Corrected all 46 names, including four that differ more than by suffix: ResourceEnabled/Disabled -> ResourceIncluded/ Excluded, AttributeChangedEvent -> ResourceAttributeUpdated. Added a warning so the distinction is hard to miss. - general.md: the environment-variable override documented a "QS_" prefix with dots replaced by underscores. No such prefix exists - EnvironmentOverrideAppSettingsReader reads the config key name verbatim. Also noted that an empty variable falls through to customer.config, and that a small number of keys read the file directly and ignore the environment. Gaps filled: - cloudshell-event-queue.md: added SandboxRouteConnected/Disconnected and SandboxCableConnected/Disconnected (2024.1.0.2529), which were undocumented in both the article and What's New. - capabilities/index.md: was a 14-item "Example Capabilities" list against 19 in Capabilities.cs. Now the complete set, with the descriptions the Portal shows as tooltips. Adds ADD_REMOVE_SANDBOX_ROUTE_CONNECTION, SET_SANDBOX_START_TIME, SET_SANDBOX_END_TIME, SHARE_UNSHARE_SANDBOX_RESOURCE, MOVE_RESOURCE. - attributes.md: added the four Assembly Lab / abstract-resolution attribute rules - Abstract Strategy Match All, Fixed, Fixed Connectivity and WorkOrderSkipMoveCheck. - customizing-email-notification-templates.md: documented EmailTemplatesDirectory (2024.1.0.2529), which is the answer to the upgrade-overwrites-your-templates warning already on that page. Version attributions were checked against the release branches rather than the Trunk changeset dates: all five events and EmailTemplatesDirectory were backported and shipped in 2024.1 patches, not 2025.1. The backport comment on CS 188481 understates its range, so the branch file contents are the authority. sandbox-stop.md and the cancel-pending/env-override What's New entries were already correct and only had their patch build sharpened. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
nahumtimerman
added a commit
that referenced
this pull request
Sep 10, 2026
* Correct three fabricated mechanisms in sweep-authored docs Follow-up audit after the QS_ prefix error in #29. All three of these were written during the PR #17 catch-up from a changeset comment plus a plausible guess at the mechanism, without reading the implementation. Each one silently does nothing when followed. - AI Assistant placeholders: the key was documented as `AIChatURL`; the product, the shipped Web.config and the sample customer.config all use `AiChatUrl`. (AppSettings lookup is case-insensitive, so this one was cosmetic rather than broken.) Two placeholders were missing entirely: `{context}`, the JSON bundle of every other value - and the one used by the example Quali ships in customer.config - and `{pageContent}`, the visible page text collapsed and truncated to 2000 characters. Added both, plus a warning that either one sends on-screen Portal content to the external service, and notes that values are URL-encoded automatically and unknown placeholders resolve to empty rather than erroring. Verified against qdPortalHeader.ts and utilities.js replaceNamedTokens, not the AppSetting description string (which is itself stale - it omits pageContent, resourceList and resourceCount). - AllowUnicodeForCommandContext was documented as a CloudShell Server key. It is read by ScriptCommandExecutionOperation in TestShell/Runtime/Service, which is the Execution Server project - it owns QsExecutionServer.exe.config, whose appSettings section has file="customer.config". Setting it on the Quali Server has no effect. Corrected the component and location, and pinned the version to 2024.1.0.2669 to match What's New. - Docker Execution Server attributes were documented as one `-e ATTRIBUTE_<Name>=<Value>` flag per attribute. No such prefix is handled anywhere; es_start.sh reads a single ES_ATTRIBUTES variable containing a JSON object and forwards it as /a: to QsExecutionServerConsoleConfig. Rewrote the section against the entrypoint and Program.cs. Also audited every config key in the configuration-options tree - all 186 exist in the product, so there are no further invented key names. The "2026.1" and "2024.1" version claims on these three were checked against the release branches and are correct. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * Add 'whitespace' to spellcheck wordlist Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.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
1 participant
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.
Article-level pass over the 2024.1-patch / 2025.1 window, driven from the product source rather than from What's New. Two findings are correctness bugs — a reader following the current docs would end up with configuration that silently does nothing.
Corrections
Event queue whitelist used the wrong names
cloudshell-event-queue.mddocumented .NET class names (UserCreatedEvent,LoginEvent,SandboxUpdateEvent). TheServerEventsWhiteList.csvfile and the published message'sEventTypefield both use the friendly names fromPublishableEventsList.cs(UserCreated,Login,SandboxUpdated).Consequence: every name in the documented example CSV is rejected, and since an unrecognized name is skipped with only a log warning, a whitelist containing only names copied from the docs publishes no events at all. Confirmed this has been the convention since the feature shipped in 2023 (CS 186571) — the article was wrong from the day it was written, which is why no changeset diff ever surfaced it.
Four names differ by more than a suffix:
ResourceEnabledEventResourceIncludedResourceDisabledEventResourceExcludedSandboxDeleteEvent/SandboxUpdateEventSandboxDeleted/SandboxUpdatedAttributeChangedEventResourceAttributeUpdatedEnvironment-variable override documented a prefix that doesn't exist
general.mdsaid to setQS_+ key name with dots replaced by underscores.EnvironmentOverrideAppSettingsReadercallsEnvironment.GetEnvironmentVariable(key)with the key verbatim — no prefix, no substitution.QS_appears nowhere in config handling (only in unrelated vCenter VLAN naming). Also documented that an empty variable falls through tocustomer.config, and that a few keys read the file directly and ignore the environment.Gaps filled
SandboxRouteConnected/Disconnected,SandboxCableConnected/Disconnected(2024.1.0.2529). Missing from both the article and What's New.Capabilities.cs. Now the complete set with the descriptions the Portal shows as tooltips. AddsADD_REMOVE_SANDBOX_ROUTE_CONNECTION,SET_SANDBOX_START_TIME,SET_SANDBOX_END_TIME,SHARE_UNSHARE_SANDBOX_RESOURCE,MOVE_RESOURCE.WorkOrderSkipMoveCheck.EmailTemplatesDirectory(2024.1.0.2529) — the answer to the "upgrading overwrites your custom templates" warning already on that page.On version attributions
Checked against the release branches, not Trunk changeset dates. All five events and
EmailTemplatesDirectorywere backported and shipped in 2024.1 patches, not 2025.1 — my first draft attributed them to 2025.1 and was wrong. The backport comment on CS 188481 understates its range (188381->188421, yet it carried 188439), so branch file contents are the authority, not commit messages.sandbox-stop.mdand the cancel-pending / env-override What's New entries were already correct; only their patch builds were sharpened.Deliberately not documented
PostgreSQL migration tooling (
QualiSystems.SqlServerToPostgresqlMigrator). CS 188428 hides PostgreSQL from QsConfig on release builds, so it isn't customer-reachable — same trap asExportBlueprintPackage.Verification
npx docusaurus buildpasses. The 3 broken links it reports (intro/features/abstract-resources) are pre-existing and unrelated. Checked the diff is pure LF (0 CRLF) and that new identifiers in bare prose are backticked, sincepyspellingonly runs in CI.🤖 Generated with Claude Code