docs: explain what this is, and make the release pipeline triggerable - #24
Merged
Conversation
…iggerable The docs assumed you already knew what a Genie Agent was. Someone arriving at this repo could not tell what problem it solves, and the first code block expected an agent id they had no way to obtain. - docs/getting-started.md: a zero-to-answer walkthrough. Explains Genie itself, states plainly that an Agent must already exist and that this tool cannot create one, and shows real rendered output captured from TerminalRenderer rather than hand-drawn box art. - README: says what this is before saying why it exists. - CONTRIBUTING: what the six projects are, and why only two are packable. The .NET example is compiled against the library in CI-equivalent conditions (warnings-as-errors) rather than written from memory. Doing that surfaced that configuration is validated when IGenieClient is first resolved, throwing OptionsValidationException rather than GenieException — so the example now places that call outside the catch blocks and says why. release.yml: the dry-run input was declared and never read, and publish was gated on a tag push, so a manual dispatch could never publish and the toggle did nothing. Replaced with version + publish inputs that are actually consulted; the GitHub-release step is gated on a tag existing. RELEASING.md documents the rehearsal path (manual run, publish unticked) and the fact that NuGet never allows unpublishing. Live tests reported failure instead of skipping. The helper named SkipException returned a plain InvalidOperationException, and xunit treats a constructor exception as a failure — so a bare "dotnet test" gave a contributor without a workspace 8 red tests, contradicting the comment directly above it. Now gated with [Fact(SkipUnless = ...)], which xunit evaluates before constructing the class: 8 skipped, 0 failed.
Both were false affordances — a declared input nothing read, and a skip helper that produced a failure. Worth naming in the changelog because in each case the surrounding text asserted the opposite of the behaviour.
…dings Five independent review lenses ran over the tree. What they found, verified at source before acting: auth check constructed DatabricksCliTokenProvider directly rather than resolving the provider the client actually uses. With DATABRICKS_TOKEN set and no Databricks CLI installed — exactly the unattended setup EnvironmentTokenProvider exists to serve — the command that exists to tell you your setup works reported that it does not. It now asks the resolved provider and names which one answered. The release workflow would publish a placeholder version. With publish ticked and version blank it resolves 0.0.0-dev.<run>, and nothing stopped that reaching nuget.org, where nothing can be unpublished — while RELEASING.md stated that version is never published. The workflow now refuses the combination. Resolving an Agent by id paged the entire listing looking for it. The id form is what scripts and packs are told to prefer, and it was the slowest path: one round trip per page. Now fetched directly, gated on the id shape so that resolving by name does not pay a guaranteed 404 first. The published pack schema offered output.format: json, which the loader rejects outright — an IDE would autocomplete a value the CLI then refuses. Also: /quit was undocumented, export and feedback each carried their own copy of the target validation, and a usage error raised after the host was built bypassed ConsoleOutput and its sanitisation. Both standards lenses reported Source Link as missing and its MSBuild properties as inert. Packing and reading the emitted .pdb disproved it — the SDK has bundled Source Link since .NET 8, and the symbols already carry a commit-pinned URL. A comment in Directory.Build.props now records that, so it does not get "fixed" into a redundant package reference later.
Everything a .NET developer could act on was a snippet they had to scaffold into a project themselves. examples/dotnet-quickstart is a real console app that takes an Agent id and a question, prints the answer, the generated SQL and the rows, and maps each GenieFailureKind onto a distinct exit code. It is in the solution deliberately: an example that no longer compiles against the library is worse than no example, and a project reference means CI catches an API change the day it lands rather than after the next release. A reader copying it swaps that reference for the package. CA2007 is suppressed there with the reason in the file. It is a library rule, and a console app has no synchronization context to return to -- writing ConfigureAwait(false) in a sample would teach a reader to copy a library idiom into application code where it means nothing. Also links the existing Question Pack example from its own documentation, which showed an abbreviated copy inline while the complete file sat undiscovered.
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.
What this changes
The documentation assumed you already knew what a Genie Agent was. Someone arriving at this repo could not tell what problem it solves, and the first code block expected an Agent id they had no way to obtain.
Documentation
docs/getting-started.md(new) — a zero-to-answer walkthrough. Explains Databricks Genie itself, states plainly that a Genie Agent must already exist and be shared with you and that this tool cannot create one, and covers scripting and the .NET library.Terminal output in the walkthrough was captured from the real
TerminalRendererrather than hand-drawn, and the C# example was compiled againstLakeSpeak.Geniewith warnings-as-errors rather than written from memory. Doing that surfaced a behaviour worth documenting: configuration is validated whenIGenieClientis first resolved, throwingOptionsValidationException— notGenieException— so the example places that call outside the catch blocks and explains why.Release pipeline
release.ymldeclared adry-runinput that nothing read, and gated publishing ongithub.refstarting withrefs/tags/v. A manual dispatch therefore could never publish, and the toggle did nothing.version(optional) andpublish(defaultfalse), both actually consulted.publishticked.RELEASING.md(new) documents the rehearsal path — a manual run withpublishunticked builds, tests, packs, produces the binaries and SBOM, and attests provenance without publishing — plus thenugetenvironment gate and the fact that NuGet never allows unpublishing.Bug fix: live tests failed instead of skipping
SkipExceptionreturned a plainInvalidOperationException, and xunit treats a constructor exception as a failure. A baredotnet testgave a contributor without a Databricks workspace 8 red tests — the opposite of what the comment directly above it claimed.Now gated with
[Fact(SkipUnless = nameof(LiveWorkspaceConfigured))], which xunit evaluates before constructing the class.Verification
dotnet teston the full solution: 167 passed, 8 skipped, 0 failed (was 8 failed).dotnet format --verify-no-changes: clean.TreatWarningsAsErrors.ExitCode.cs; every CLI symbol named in the docs confirmed present in source.