microsoft / microsoft/finops-toolkit

FOCUS 1.4 phase 0: refresh hub upgrade procedure docs

Open
#2,121 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Tool: FinOps hubs Tool: FOCUS
Dominant language
PowerShell
Stars
603
Forks
248
Avg merge
7d 11h
Merged PRs (30d)
11

Description

Parent: #2120

Goal

Update the canonical "add a new FOCUS version" procedure and the user-facing data-model doc before adding 1.3/1.4. This locks in the conventions we'll follow in subsequent phases and clarifies the hub-schema-vs-FOCUS-version coupling for users.

Scope

File: src/templates/finops-hub/docs/README.md

Today's procedure (lines 20-43) covers a single-FOCUS-version-at-a-time upgrade. Updates needed:

  1. Add a step 0: "Confirm Cost Management has shipped the matching FOCUS export dataset version. If not, ship hub support as preview and document the dependency."
  2. Add notes for adding two versions in one cycle (e.g., 1.3 + 1.4): the older one becomes a regular _vX_Y, the newer one is preview-suffixed; the latest unversioned function points to whichever is ratified.
  3. Add a step for plugin updates (link to plugin skill files in src/templates/agent-skills/).
  4. Add a step for conformance regen: run Build-FocusConformance.ps1 with the new FOCUS branch to refresh docs-mslearn/focus/conformance-full-report.md and conformance-summary.md.
  5. Add a step for open-data metadata: drop a new FocusCost_<version>.json into src/open-data/dataset-metadata/.
  6. Add a step for changelog: add an entry under the next version in docs-mslearn/toolkit/changelog.md.
File: docs-mslearn/toolkit/hubs/data-model.md

Current schema-version table is clear but doesn't explain the why of the 1:1 coupling between hub schema version and FOCUS version. Add:

  • A short paragraph stating the hub schema version mirrors the FOCUS version it natively ingests (e.g., v1_2 ingests FOCUS 1.2 cleanly).
  • Clarification that the unversioned function (Costs()) always returns the latest schema version, transparently up-converting older data.
  • Note about preview hub schemas: when the toolkit ships hub support ahead of a FOCUS spec ratifying or ahead of Cost Management exporting that version, the hub schema is labeled preview.

Branch

flanakin/focus14-phase0-docs off flanakin/focus14. PR target: flanakin/focus14.

Done when

  • README.md upgrade procedure reflects all six additions.
  • data-model.md clarifies the version coupling and preview convention.
  • PR opened against flanakin/focus14.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the upgrade procedure in src/templates/finops-hub/docs/README.md, especially lines 20-43, then read docs-mslearn/toolkit/hubs/data-model.md. Review Build-FocusConformance.ps1 and the named metadata and changelog paths to understand the referenced regeneration and documentation steps. Done means both documents contain the requested version, preview, plugin, conformance, metadata, and changelog guidance, with a PR opened against flanakin/focus14.

Written by the indexing model from the issue text.

Assessment

Tech stack
powershell
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
72/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.