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).
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/15/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.

RolandKrummenacher · 2026-06-29T07:02:41Z

+To add a new FOCUS version:

+0. Confirm dependencies
+   1. Ensure the FOCUS specification has been ratified for the target version. Support for working draft FOCUS versions should not be shipped before official ratification to prevent customer churn sinc FOCUS working drafts may change without notice.


Typo: sinc -> since.

RolandKrummenacher · 2026-06-29T07:02:41Z


+0. Confirm dependencies
+   1. Ensure the FOCUS specification has been ratified for the target version. Support for working draft FOCUS versions should not be shipped before official ratification to prevent customer churn sinc FOCUS working drafts may change without notice.
+   2. Check whether Microsoft Cost Management has shipped a matching FOCUS export dataset version. The hub depends on a `focuscost_X.Y.json` schema mapping file in [Microsoft.CostManagement/Exports/schemas](../modules/Microsoft.CostManagement/Exports/schemas/) when ingesting from Cost Management. If the export is not yet available, the hub schema can still ship as GA. Note the gap in the changelog so adopters know what additional setup will be required.


The PR summary says step 0 should instruct shipping hub support as preview when the Cost Management export is not yet available, but this line says ship as GA (and data-model.md has no preview-convention text). Please reconcile the description with what shipped here. The body also lists "steps 5-8" but only 5-7 landed.

RolandKrummenacher · 2026-06-29T07:02:41Z

   3. Update the ADX dashboard to use the new versioned functions
   4. Update the FOCUS queries in the best practices library to use the new versioned functions
+5. Update open-data metadata
+   1. Create a `FocusCost_<version>.json` file into [src/open-data/dataset-metadata](../../../open-data/dataset-metadata/) for each Cost Management cost export version.


Nit: "file into [folder]" -> "file in [folder]". Same on the next line (5.2).

RolandKrummenacher · 2026-06-29T07:02:41Z

 | Release | Schema | FOCUS version |
 | ------- | ------ | ------------- |
-| 12+     | `v1_2` | 1.2           |
+| 15+     | `v1_4` | 1.4           |


Forward-dated content in a published Learn page: this adds a 15+ -> v1_4 -> 1.4 row (and v1_4/Costs_v1_4 examples on line 55) before 1.4 support has shipped. If docs-mslearn publishes on merge rather than gated to the 1.4 release, this page would publicly state 1.4 is supported ahead of release. Consider holding the v1_4 row/examples for a later phase, or confirm the publish cadence makes this safe.

RolandKrummenacher · 2026-06-29T07:02:41Z

+
+Data is transformed to the latest supported FOCUS version during ingestion. For instance, if you ingested FOCUS 1.0 data into the `v1_4` schema, it would be converted to FOCUS 1.4 during ingestion. Older data remains in its originally ingested format. For instance, if you previously ingested FOCUS 1.0 data into the `v1_2` schema, it would remain in the `v1_2` format even after upgrading to a newer schema version.
+
+The functions in the `Hub` database pull from all tables and transform it into a specific version. For instance, `Costs_v1_0` will convert `v1_4` and `v1_2` data back to the `v1_0` format, ensuring backwards compatibility despite upgrading to newer versions. When you're ready to upgrade, you can selectively upgrade each report or integration to use `Costs_v1_2` or `Costs_v1_4` without breaking others. However, if you want a quick, convenience function that always returns the latest version, you can use the unversioned functions, like `Costs` and `Prices`. Unversioned functions are recommended for ad hoc use while versioned functions are recommended for integration points that require a consistent format after upgrades.


Minor: "pull from all tables and transform it" -> "them" (refers to the tables).

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).

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


		Data is transformed to the latest supported FOCUS version during ingestion. For instance, if you ingested FOCUS 1.0 data into the `v1_4` schema, it would be converted to FOCUS 1.4 during ingestion. Older data remains in its originally ingested format. For instance, if you previously ingested FOCUS 1.0 data into the `v1_2` schema, it would remain in the `v1_2` format even after upgrading to a newer schema version.

		The functions in the `Hub` database pull from all tables and transform it into a specific version. For instance, `Costs_v1_0` will convert `v1_4` and `v1_2` data back to the `v1_0` format, ensuring backwards compatibility despite upgrading to newer versions. When you're ready to upgrade, you can selectively upgrade each report or integration to use `Costs_v1_2` or `Costs_v1_4` without breaking others. However, if you want a quick, convenience function that always returns the latest version, you can use the unversioned functions, like `Costs` and `Prices`. Unversioned functions are recommended for ad hoc use while versioned functions are recommended for integration points that require a consistent format after upgrades.

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!

RolandKrummenacher Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

RolandKrummenacher Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

RolandKrummenacher Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

RolandKrummenacher Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

RolandKrummenacher Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

flanakin commented Jul 15, 2026

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