docs: line comments in the query language - #206
Open
ManuelGerding wants to merge 6 commits into
Open
Conversation
A query can now carry a `//` comment, so the reason a target was excluded lives next to the exclusion. Two caveats get their own bullets because both surprise people. A `//` inside a quoted value is part of the value, not a comment, so URLs keep working. And a query made up of nothing but comments is an empty query, which matches everything -- commenting a query out widens it rather than emptying it. Note this page already used `//` for its own annotations in two examples, which until now would have been syntax errors if pasted into the editor. They are valid as of this release.
… query "An empty query matches everything" read as if commenting a query out could reach past the environment it lives in, or past what a team is permitted to use. It cannot: a query is always ANDed with its scope, so it only ever narrows what that scope already contains. The bullet now says that, and spells out the two ordinary cases -- a blast radius stays within the experiment's environment and the action's target type, a service scope within its environment -- before naming the one that really is tenant-wide: an environment's own scope, where the query is the boundary rather than a filter inside one. Also drops a line break from the first example. The comment is what needs its own line; splitting the query across two suggested the AND had to be there.
The page went from `#` straight to `###`, then to `####` for each example, so every section sat one level deeper than it needed to and the top level was skipped entirely. Promoting each by one gives `#` > `##` > `###` with nothing missing, which is what the page-level table of contents and screen readers both read the structure from. Headings only -- verified no line inside a code fence starts with `#`, and no other page links to this one by anchor. Anchors derive from heading text rather than level in any case, so existing links are unaffected.
Note this changes that heading's anchor. Nothing in the repository referenced it -- SUMMARY.md links the page rather than the heading, and no other page links this one by anchor -- and an anchor carrying the misspelling is unlikely to have been linked deliberately from outside.
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.
Documents line comments in the query language, shipping in the next platform release.
Platform PR: https://github.com/steadybit/platform/pull/1974
BusinessMap 24059
Adds a
#### Commentssection toconcepts/query-language/README.md, matching the shape of the sections around it: what it is, a comment on its own line, a comment trailing a query, and where it works.Two caveats get their own bullets because both surprise people:
//inside a quoted value is part of the value, not a comment, so"label.url"="https://example.com"keeps working.One thing worth knowing: this page already used
//for its own annotations in two existing examples (// Matches all, but not prodand// Quoting keys with special characters is necessary). Until now those would have been syntax errors if a reader pasted them into the query editor. As of this release they are valid, so the examples are now literally correct rather than only illustrative.Should merge once the platform PR is released, not before.
🤖 Generated with Claude Code