Skip to content

DECISIONS.md

Latest commit

 

History

History
51 lines (41 loc) · 11 KB

DECISIONS.md

File metadata and controls

51 lines (41 loc) · 11 KB
Raw

Decisions

  • 2026-09-28: Keep coding-agent model catalogs as documented built-in fallbacks shared by CLI listing and validation, while accepting arbitrary nonblank full model IDs in evaluation targets. Copilot and Claude lack reliable noninteractive catalog commands and Codex may not be installed; account policy can further narrow availability, so the isolated no-tools agent preflight is authoritative. Add Codex through deterministic ephemeral codex exec --json, with workspace-write only for generated evaluation workspaces and read-only for preflight. Keep the local non-secret eval/configuration.yml ignored while tracking its example.
  • 2026-09-25: Add the Microsoft open source root files (LICENSE, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, SUPPORT.md, NOTICE.txt), modelled on microsoft/microsoft-sql and adapted to this site. The privacy document stays as the published privacy.md page rather than a root PRIVACY.md: the two names differ only in case, so a case insensitive checkout cannot hold both, and separating them would move this page's markdown twin off its URL. privacy.md now carries the Clarity disclosure and the Microsoft data collection notice.
  • 2026-09-25: Hold the branded hero thumbnail for two seconds once the hero is in view, then play the demo silently one time with controls available, and return to the thumbnail behind a Replay button. Reduced-motion visitors, and any browser that refuses playback it did not see asked for, keep the thumbnail and a Play demo button.
  • 2026-09-16: Keep validation tracking and agent-file documentation in repository docs; remove the For agents page from publishing and human navigation while retaining machine-readable files and alternate links.
  • 2026-09-16: Use visual links to existing SQL videos without auto-playing or embedding a player; retain a complete hero without a demo placeholder.

One dated line per irreversible or debatable choice. Append to this file in any pull request that makes one. Do not rewrite past entries: if a decision is reversed, add a new line saying so and why.

  • 2026-09-02: anchor ids start, connect, build, skills, samples on the home page, permanent. External links, documentation, and agents point at these, so they are chosen once and never renamed.

  • 2026-09-02: static Jekyll on GitHub Pages over Docusaurus or any JavaScript framework. Agent readability is the point of this site, and a markdown source that renders itself keeps the page and the machine-readable version from drifting.

  • 2026-09-02: every page is a .md file published twice, once as HTML and once as its own source at <page>.md. One source file, two outputs, so the twin cannot go stale.

  • 2026-09-02: home page hero and path-card copy live in index.md front matter rather than the body, because the layout needs it as structured data. scripts/build-agent-files.mjs renders it back into markdown for the .md twin so the twin stays complete.

  • 2026-09-02: tabs and copy buttons are progressive enhancement. Panels render as stacked headings with no JavaScript, so no content depends on a script running.

  • 2026-09-02: design tokens copied verbatim from the Azure SQL Database container site rather than reinterpreted, so the two properties read as one family. One deliberate difference: azure blue is reserved for interactive elements here, and labels and accents use the cyan or muted ink instead.

  • 2026-09-02: the nav renders only anchors whose sections exist. The full permanent id list lives in _config.yml as nav_anchors with a live flag. Shipping a nav link that scrolls nowhere was judged worse than a nav that grows in a later pull request.

  • 2026-09-02: the home page describes the Azure SQL Database free offer as needing an Azure account and subscription, and does not say "no credit card". The offer documentation lists an Azure account and subscription as prerequisites and makes no claim about payment methods.

  • 2026-09-02: Application Insights is wired but disabled, with no connection string. The container site's connection string is public and reusable, but sending this site's traffic to that resource would mix two properties' telemetry with no clean way to separate it later. This hub gets its own resource before analytics is switched on.

  • 2026-09-02: the house-rules check is a script run by both CI and npm test, not inline workflow YAML, so a local green run and a CI green run mean the same thing.

  • 2026-09-02: the deploy workflow derives url and baseurl from the Pages API at build time rather than reading them from _config.yml. This repository is private, so Pages publishes to a generated *.pages.github.io domain at the root instead of microsoft.github.io/azure-sql-dev-hub. Hardcoding either value would break absolute_url, which is what llms.txt and the og:url tag are built from, and would need another edit if the repository is made public.

  • 2026-09-08: the V8 mockup's visual language supersedes the container-inherited tokens from PR 1. Light page, Microsoft blue, Inter, dark surfaces only for code. The owner approved V8 as the design of record; this line supersedes the 2026-09-02 token decision.

  • 2026-09-08: the V8 information architecture supersedes the original anchor set. build and skills remain; get-running replaces start, which stays as an invisible alias anchor so old links still land; connect and samples were retired before any nav ever rendered them; prompts, continuity, and existing are new sections. This line supersedes the 2026-09-02 anchor decision.

  • 2026-09-08: scenarios are real pages under /build/.html with .md twins, not modals. A URL an agent can fetch and a person can share is the product thesis; the mockup's modal was a preview stand-in.

  • 2026-09-08: the cloud quickstart uses the Azure CLI free-offer command. It is verbatim a documented example in the az sql db create reference, so it is canonical, not invented.

  • 2026-09-08: the multi-tenant starter uses the SESSION_CONTEXT predicate pattern from the Row-Level Security documentation rather than the mockup's fragment, which referenced a predicate function it never defined.

  • 2026-09-08: no .well-known discovery files. No current artifact defines one: there is no Azure SQL MCP endpoint yet, and llms.txt lives at the site root by convention. Inventing a discovery surface that points at nothing would be worse than absence; /for-agents documents what exists.

  • 2026-09-08: telemetry stays behind one track() that logs to the console for the demo and fans out to App Insights when configured. quickstart_start fires only on user interaction, not on page load as in the mockup, so the metric means a person chose a path.

  • 2026-09-08: repository visibility changed from private to internal, on the owner's decision, so everyone in the Microsoft enterprise can view the demo site after signing in. The Pages site stays privately published on the same generated domain; nothing is exposed to the public internet. Public visibility was considered and rejected for a pre-release demo.

  • 2026-09-11: propose six cloud-first application prompts across JavaScript, Python, and .NET before engineering handoff. Preserve existing scenario URLs. Container setup becomes an optional signup path; new prompts remain explicitly draft until reproduced and validated.

Decisions for the SQLCon review

2026-09-16: Feature three cloud-first draft prompts for a focused review; retain earlier URLs, and require engineering execution evidence before launch claims. 2026-09-16: Engineering owns both Clarity telemetry implementation and prompt validation; PM owns content, mockup approval and launch messaging. 2026-09-16: Exclude local output packages from site publishing and agent indexes; omit unavailable video placeholders. 2026-09-22: Enable Microsoft Clarity as the first production analytics provider, using Strict masking, Clarity cookies disabled, no custom user identifiers, and a site privacy disclosure. Existing action names fan out through track() to Clarity custom events; only stable allowlisted dimensions become session-level custom tags. 2026-09-24: The agent skills repository was renamed from microsoft/azure-sql-skills to microsoft/microsoft-sql, and the product is now Microsoft SQL Agent Skills. aka.ms/azuresql-skills was repointed at the new repository, so the short link is unchanged everywhere it appears. Install commands were updated across the site, llms.txt, and the README: npx skills add microsoft/microsoft-sql, claude plugin marketplace add microsoft/microsoft-sql with claude plugin install microsoft-sql@microsoft-sql, and gh skill install microsoft/microsoft-sql. The Skills nav item keeps its short label; the section heading carries the product name. This line supersedes the 2026-09-16 note that install commands and skills links point at microsoft/azure-sql-skills. 2026-09-25: Preserve aggregate telemetry event names and add a second stable Clarity custom event for interactions that need item-level reporting. Prompt copy and view events include the scenario slug, skill installation copies include the selected harness, and suggested ask copies include a non-content prompt key. The Browse the skills call to action sends browse_skills. This avoids using Clarity session-level custom tags as if they were event properties and sends no copied prompt or command content.

2026-09-16: Hub prompts are cloud-scoped, and need a cloud accuracy baseline

The six build prompts target Azure SQL Database in the cloud (free offer), not the container. The container is Private Preview until Ignite, so a prompt that needs it would fail for a stranger on launch day. The container's own prompts stay local-scoped on the container site; the Hub's stay cloud-scoped. Same jobs, different target, no duplication.

Consequence for hub-new-prompt (contributor skill, drafted, not yet implemented): its accuracy baseline is the container baseline (image, EngineEdition=5, SQL_CONNECTION_STRING, --platform linux/amd64). Cloud prompts cannot hold it. They need a second baseline: Entra over passwords, Encrypt=true and TrustServerCertificate=false, the 40613 retry on auto-pause, the 529 vector cast, primary key and compat level 130 for Functions output bindings. The six prompts follow that baseline today; the skill should encode it before it gates anything.

2026-09-16: Homepage design and prompt files

Human layer added on top of the agent layer: hero video with chapter stamps, three setup paths as tabs, six scenario cards with illustrations, workload tiles, agent selector that switches the install command, video reel. Prompts moved from short front matter strings to full instruction sets in build/*.md (role, purpose, scope, numbered steps, validation rules, do-nots), matching the container site's prompt structure. The homepage Copy button fetches the page's markdown twin, so the card and the file cannot drift. dotnet-app replaced by multi-tenant; the .NET framework is covered by the serverless and event-driven scenarios. All install commands and skills links point at microsoft/azure-sql-skills (aka.ms/azuresql-skills), which launches at SQLCon alongside the Hub.