Refresh FinOps hub upgrade procedure for multi-version FOCUS adoption by flanakin · Pull Request #2123 · microsoft/finops-toolkit

flanakin · 2026-05-06T09:45:18Z

🛠️ Description

Refreshes the FinOps hub upgrade procedure (README.md step 0) and data-model.md for multi-version FOCUS adoption, decoupling hub preview status from Cost Management export availability.

Preview now means the FOCUS spec itself is still a working draft (not ratified) — not that Cost Management hasn't shipped an export yet. Cost Management export lag is documented as a separate operational concern; a hub schema can be GA before Cost Management ships a matching export, and the hub ingests the new format as soon as it becomes available.
Phase 4 (IngestionSetup_v1_4.kql) and phase 5 (HubSetup_v1_4.kql) already correctly mark v1_4 as preview because FOCUS 1.4 is a working draft, not because of any Cost Management gap — no downstream PRs need adjusting for this change.
Addressed review feedback: typo fixes (sinc → since; "file into [folder]" → "file in [folder]", two occurrences; "pull from all tables and transform it" → "transform them" for subject-verb agreement), reconciled the PR body/step language with what shipped (GA-based dependency checks, step count corrected to steps 5-7, added a scope note that per-version column-change tables land in a separate docs PR, W6).
Clarified the data-model.md "Schema version" prose: reworded the ingestion paragraph so data is transformed to the schema version of the current hub release (not the "latest FOCUS version"), tightened the Cost Management export-availability note, fixed a copy-paste error ("Unversioned functions, like Costs_v1_0()" → "Versioned functions"), and documented the -preview suffix convention in README.md step 5.1.
Forward-dated v1_4 content intentionally left in docs-mslearn/toolkit/hubs/data-model.md: this branch merges into the flanakin/focus14 integration branch, not directly into dev, so the content only reaches Learn publishing when the integration branch itself merges as part of the 1.4 release.

Verification

git diff scoped to the exact lines called out in review; re-grepped for sinc and file into — 0 hits remaining in both cases.
ms.date set to 07/25/2026 in docs-mslearn/toolkit/hubs/data-model.md per repo convention for modified Learn pages.

📋 Checklist

🔬 How did you test this change?

🤏 Lint tests

🤞 PS -WhatIf / az validate

👍 Manually deployed + verified

💪 Unit tests

🙌 Integration tests

📦 Deploy to test?

Hubs + ADX (managed)

Hubs + Fabric (manual) — URI:

Hubs (manual)

Hubs (no data)

Workbooks

Alerts

🙋‍♀️ Do any of the following that apply?

🚨 This is a breaking change.

🤏 The change is less than 20 lines of code.

…#2121) Update the canonical "add a new FOCUS version" procedure to reflect the six additional steps surfaced during FOCUS 1.4 scoping (Cost Management dependency check, open-data metadata, conformance regen, plugin updates, changelog) and add guidance for handling two FOCUS versions in one cycle (GA + preview). Clarify the hub-schema-to-FOCUS-version relationship and preview convention in data-model.md. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Refreshes the FinOps hubs documentation playbook for adding new FOCUS versions, with explicit guidance for preview vs GA handling and a clearer explanation of how hub schema versions relate to FOCUS spec versions.

Changes:

Expanded the “add a new FOCUS version” procedure with dependency checks, open-data metadata, conformance regeneration, plugin reference updates, and changelog guidance.
Added guidance for handling two FOCUS versions in a single release cycle (GA + preview) and keeping unversioned functions pinned to latest GA.
Clarified in user docs that hub schema versions mirror the FOCUS version they natively ingest, and documented the preview convention.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
src/templates/finops-hub/docs/README.md	Updates the canonical upgrade procedure and adds multi-version (GA + preview) guidance.
docs-mslearn/toolkit/hubs/data-model.md	Clarifies schema-version-to-FOCUS coupling and documents preview behavior for hub schemas.

Conformance reports are generated only against official Microsoft Cost Management FOCUS releases, not as part of adding a new FOCUS version to FinOps hubs. Removing the step keeps the procedure scoped to the hub-specific workstream. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

flanakin · 2026-05-07T10:40:34Z

🤖 [AI][Claude Code] Additional change beyond Copilot review

While addressing the grammar fix on data-model.md:66, surfaced a broader concern: the original wording conflated two distinct preview triggers — FOCUS spec maturity (legit) and Cost Management export availability (not legit, since hubs has its own lifecycle and shouldn't be permanently gated by another team's roadmap).

Updated both data-model.md and the README's step 0 to decouple them:

Preview = FOCUS spec is still working draft (not ratified).
Cost Management export availability is now described as a separate operational concern. A hub schema can be GA before Cost Management ships an export — the hub will ingest the new format as soon as the export becomes available.

Phase 4 (IngestionSetup_v1_4.kql) and phase 5 (HubSetup_v1_4.kql) already correctly mark v1_4 as preview because FOCUS 1.4 is working draft, not because of any Cost Management gap, so no downstream PRs need adjusting.

- Reword data-model.md:66 grammar (per Copilot). - Decouple hub preview status from Cost Management export availability. Preview now means the FOCUS spec is still working draft. Cost Management lag is a separate operational concern that does not gate hub GA. - Update README step 0 to match. Co-Authored-By: copilot-pull-request-reviewer <copilot-pull-request-reviewer@users.noreply.github.com> Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

flanakin · 2026-05-07T10:40:54Z

🤖 [AI][Claude Code] PR Update Summary

Addressed: 1 review thread + scope expansion

✅ Implemented: 1 (Copilot grammar fix on data-model.md:66)
💬 Scope change: Decoupled hub preview status from Cost Management export availability. Hubs preview = FOCUS spec is working draft; Cost Management lag is a separate operational concern documented in changelog, not a GA gate.

RolandKrummenacher

Superseded — see the inline comments in this review for the line-anchored findings.

RolandKrummenacher

Inline comments added below. Docs-only and low-risk — verified all relative links resolve and the open-data naming/up-conversion details are accurate. Recommend fixing the typo and reconciling the GA-vs-preview wording before merge.

Addresses PR #2123 review nits: "sinc" -> "since", "file into" -> "file in" (x2), and "transform it" -> "transform them" for grammatical agreement with "tables". Also refreshes ms.date on the modified docs-mslearn page. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

flanakin · 2026-07-15T19:37:41Z

Pushed 463c273 addressing the outstanding review feedback:

Comment	Fix
3489844997	Typo `sinc` -> `since` in README.md step 0.1.
3489845004	README.md steps 5.1/5.2: "file into [folder]" -> "file in [folder]" (both occurrences).
3489845010	data-model.md: "pull from all tables and transform it" -> "transform them" (agreement with "tables").
3489845002	PR body reconciled with what shipped: step 0 language now reflects GA-based dependency checks (no "preview" claim), step count corrected to steps 5-7, and a scope line added clarifying per-version column-change tables land in a separate docs PR (plan W6).

Also set ms.date to 07/15/2026 in docs-mslearn/toolkit/hubs/data-model.md per repo convention for modified Learn pages.

On comment 3489845007 (forward-dated v1_4 content): left as-is, not removed. Rationale: this branch merges into flanakin/focus14 (an integration branch), not directly into dev. The docs-mslearn content only reaches dev — and therefore Learn publishing — when the FOCUS 1.4 integration branch itself merges to dev, which happens as part of the 1.4 release. So the v1_4 row/examples are correctly gated by the integration branch structure rather than needing to be held back within this PR. Flagging this explicitly so the rationale can be vetoed if the publish/branch topology differs from this understanding.

Diff is scoped to the exact lines called out — verified via git diff and re-grepped for sinc and file into (0 hits remaining in both cases).

…rding Address review feedback on the FOCUS multi-version docs refresh: - data-model.md: reword the "Schema version" ingestion paragraph to say data is transformed to the current release's schema version (not the "latest FOCUS version"), and that older data stays in the schema version it was originally ingested into. Removes the apparent ingestion-vs-query contradiction while matching the actual KQL update-policy behavior. - data-model.md: tighten the Cost Management export-availability note by dropping the vague "(forward or backward, depending on your release)" parenthetical. - data-model.md: fix copy-paste error — "Unversioned functions, like Costs_v1_0()" should read "Versioned functions". - README.md: note the `-preview` suffix convention for working-draft FOCUS versions in the open-data metadata step. Co-Authored-By: RolandKrummenacher <RolandKrummenacher@users.noreply.github.com> Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Copilot AI review requested due to automatic review settings May 6, 2026 09:45

flanakin requested review from MSBrett and RolandKrummenacher as code owners May 6, 2026 09:45

Copilot started reviewing on behalf of flanakin May 6, 2026 09:45 View session

microsoft-github-policy-service Bot added the Needs: Review 👀 PR that is ready to be reviewed label May 6, 2026

microsoft-github-policy-service Bot assigned MSBrett May 6, 2026

Copilot AI reviewed May 6, 2026

View reviewed changes

Comment thread docs-mslearn/toolkit/hubs/data-model.md Outdated

flanakin mentioned this pull request May 6, 2026

FOCUS 1.3 and 1.4 support across the toolkit #2120

Open

13 tasks

flanakin marked this pull request as draft May 6, 2026 23:16

flanakin added this to the v15 milestone May 15, 2026

flanakin commented May 17, 2026

View reviewed changes

Apply suggestions from code review

6053f28

flanakin marked this pull request as ready for review May 17, 2026 20:16

chore: Update ms.date in docs-mslearn files

8ee2d63

microsoft-github-policy-service Bot assigned flanakin May 17, 2026

flanakin added the Status: 🔁 Updated PR is updated with the latest feedback label May 28, 2026

RolandKrummenacher reviewed Jun 17, 2026

View reviewed changes

RolandKrummenacher reviewed Jun 29, 2026

View reviewed changes

flanakin added Needs: Attention 👋 Issue or PR needs to be reviewed by the author or it will be closed due to no activity and removed Needs: Review 👀 PR that is ready to be reviewed Status: 🔁 Updated PR is updated with the latest feedback labels Jun 29, 2026

flanakin mentioned this pull request Jul 15, 2026

Add FOCUS 1.4 support #2207

Draft

30 tasks

microsoft-github-policy-service Bot removed the Needs: Attention 👋 Issue or PR needs to be reviewed by the author or it will be closed due to no activity label Jul 15, 2026

microsoft-github-policy-service Bot added Needs: Triage 🔍 Untriaged issue needs to be reviewed Needs: Review 👀 PR that is ready to be reviewed labels Jul 15, 2026

This was referenced Jul 15, 2026

Add FOCUS 1.4 schema tests and changelog entries #2136

Draft

Add FOCUS 1.4 schema documentation (upgrade, compatibility, data dictionary) #2211

Draft

flanakin commented Jul 25, 2026

View reviewed changes

Comment thread docs-mslearn/toolkit/hubs/data-model.md Outdated

Comment thread docs-mslearn/toolkit/hubs/data-model.md

Comment thread src/templates/finops-hub/docs/README.md

flanakin and others added 5 commits July 25, 2026 11:15

Update docs-mslearn/toolkit/hubs/data-model.md

92f1178

chore: Update ms.date in docs-mslearn files

e24f5f0

Fix schema file naming reference

626ecd8

chore: Update ms.date in docs-mslearn files

3263271

flanakin merged commit 4f69e56 into flanakin/focus14 Jul 26, 2026
1 check passed

flanakin deleted the flanakin/focus14-phase0-docs branch July 26, 2026 16:56

flanakin deployed to ftk-pr July 26, 2026 16:56 — with GitHub Actions Active

Uh oh!

Conversation

flanakin commented May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🛠️ Description

Verification

📋 Checklist

🔬 How did you test this change?

📦 Deploy to test?

🙋‍♀️ Do any of the following that apply?

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

flanakin commented May 7, 2026

Uh oh!

flanakin commented May 7, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

RolandKrummenacher left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RolandKrummenacher left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

flanakin commented Jul 15, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

flanakin commented May 6, 2026 •

edited

Loading

RolandKrummenacher left a comment •

edited

Loading