diff --git a/.github/ISSUE_TEMPLATE/discussion-topic.yml b/.github/ISSUE_TEMPLATE/discussion-topic.yml index 04310627b..08d54d674 100644 --- a/.github/ISSUE_TEMPLATE/discussion-topic.yml +++ b/.github/ISSUE_TEMPLATE/discussion-topic.yml @@ -2,7 +2,7 @@ name: Discussion Topic description: Initiate discussion on broad topics within the FOCUS community. title: "[DISCUSSION]: " labels: ["discussion topic"] -assignees: ["mike-finopsorg,udam-f2"] +assignees: ["shawnalpay"] body: - type: textarea attributes: diff --git a/.github/ISSUE_TEMPLATE/feedback.yml b/.github/ISSUE_TEMPLATE/feedback.yml index 1ab51c5c0..656903ca8 100644 --- a/.github/ISSUE_TEMPLATE/feedback.yml +++ b/.github/ISSUE_TEMPLATE/feedback.yml @@ -1,14 +1,14 @@ -name: FinOps Use Case Feedback -description: Provide feedback on FinOps use cases that cannot be performed with the current FOCUS specification. +name: Feature Request and Use Case Feedback +description: Provide feedback on unsupported use cases or features in the FOCUS specification, including FinOps scenarios, to help prioritize updates. Avoid sharing proprietary information. title: "[FEEDBACK]: " -labels: [""] -assignees: ["mike-finopsorg,udam-f2"] +labels: ["use case"] +assignees: ["shawnalpay, jpradocueva,"] body: - type: markdown attributes: - value: "The FOCUS working group wants to understand what FinOps use cases cannot be performed today using the current specification so they can be prioritized for upcoming release. Please do not provide any information that may be considered Intellectual Property by any individual or organization." + value: "FOCUS working group seeks gaps in the current specification for FinOps and beyond. Share unsupported use cases or features to prioritize updates. Avoid sharing proprietary information." - - type: input + - type: textarea attributes: label: Proposed Change description: Short description of the change and why it is necessary. @@ -18,8 +18,8 @@ body: - type: textarea attributes: - label: What FinOps use cases cannot be performed without the proposed change? - description: Describe in detail the current FinOps use cases your organization cannot perform without the proposed change + label: What use cases, FinOps or others, can't be performed with the current specification without this change? + description: Describe in detail the use cases, whether FinOps-related or otherwise, that your organization cannot perform with the current specification without the proposed change. validations: required: true @@ -51,6 +51,14 @@ body: validations: required: true + - type: textarea + attributes: + label: Key Metrics and KPIs + description: List the metrics and KPIs that will measure the success of this use case (e.g., cost per service, spend reduction percentage). + placeholder: e.g., cost per service, spend reduction percentage, etc. + validations: + required: false + - type: textarea attributes: label: Context / Supporting information @@ -66,4 +74,3 @@ body: placeholder: Attach sample data or data extracts here. Ensure compliance with data privacy guidelines. validations: required: false - diff --git a/.github/ISSUE_TEMPLATE/maintenance.yml b/.github/ISSUE_TEMPLATE/maintenance.yml index 3a39989ce..daae0715e 100644 --- a/.github/ISSUE_TEMPLATE/maintenance.yml +++ b/.github/ISSUE_TEMPLATE/maintenance.yml @@ -2,7 +2,7 @@ name: Maintenance Task description: Create tasks related to work on the GitHub Repository or GitHub Actions. title: "[MAINTENANCE]: " labels: ["repo maintenance"] -assignees: ["mike-finopsorg,udam-f2"] +assignees: ["shawnalpay"] body: - type: textarea attributes: diff --git a/.github/ISSUE_TEMPLATE/spec-change.yml b/.github/ISSUE_TEMPLATE/spec-change.yml index 344bdcc8c..aa4104c63 100644 --- a/.github/ISSUE_TEMPLATE/spec-change.yml +++ b/.github/ISSUE_TEMPLATE/spec-change.yml @@ -2,7 +2,7 @@ name: Spec Change description: Submit changes or updates to the current specification. title: "[SPEC CHANGE]: " labels: ["discussion topic"] -assignees: ["mike-finopsorg,udam-f2"] +assignees: ["shawnalpay"] body: - type: dropdown attributes: diff --git a/.github/ISSUE_TEMPLATE/work-item.md b/.github/ISSUE_TEMPLATE/work-item.md new file mode 100644 index 000000000..e8c3b7d2b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/work-item.md @@ -0,0 +1,53 @@ +# Work Item Issue Template +description: +title: "[Work_Item]" +labels: ["work item"] +assignees: [shawnalpay, jpradocueva] + +### **Template Usage Notes**: +1. All fields marked as **mandatory** [*] must be filled before submission. While some datapoints are optional for the initial creation of the work item, all datapoints must be provided in order to be considered for spec development. +2. If you have suggestions for the specification but cannot fill out all fields in this issue template, please fill out a [Feedback] or [Discussion] issue template instead. +3. For **Supporting Documentation**, ensure that linked files are accessible to relevant stakeholders. + +--- + +## 1. **Problem Statement** * +Describe the problem, issue, use case, or opportunity that this work item addresses. +Include practitioner quotes illustrating real examples a) of questions being asked by practitioners and b) value unlocked by answering these questions, if available. +- **What is the problem?**: Explain the context and why it needs resolution. +- **Impact**: Describe how the problem affects users, systems, or the project. + +Your input ... + +## 2. **Objective** * +State the objective of this work item. What outcome is expected? +- **Success Criteria**: Define how success will be measured (e.g. metrics and KPIs). + +Your input ... + +## 3. **Supporting Documentation** * +Include links to supporting documents such as: +- Data Examples: [Link to data or relevant files; DO NOT share proprietary information] +- Related Use Cases or Discussion Documents: [Link to discussion] +- PRs or Other References: [Link to relevant references] + +Your input ... + +## 4. **Proposed Solution / Approach** +Outline any proposed solutions, approaches, or potential paths forward. Do not submit detailed solutions; please keep suggestions high-level. +- **Initial Ideas**: Describe potential solution paths, tools, or technologies. +- **Considerations**: Include any constraints, dependencies, or risks. +- **Feasibility**: Include any information that helps quantify feasibility, such as perceived level of effort to augment the spec, or existing fields in current data generator exports. +- **Benchmarks**: Are there established best practices for solving this problem available to practitioners today (e.g. mappings from existing CSP exports that are widely used)? + +Your input ... + +## 5. **Epic or Theme Association** +> This section will be completed by the Maintainers. +> - **Epic**: [Epic Name] +> - **Theme**: [Theme Name, if applicable] + +## 6. **Stakeholders** * +List the main stakeholders for this issue. +- **Primary Stakeholders**: [Name/Role] +- **Other Involved Parties**: [Names/Roles] diff --git a/.github/ISSUE_TEMPLATE/work-item.yml b/.github/ISSUE_TEMPLATE/work-item.yml new file mode 100644 index 000000000..bc422b790 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/work-item.yml @@ -0,0 +1,121 @@ +name: "Work Item Issue Template" +description: "Template for creating new work item issues" +title: "[Work_Item]" +labels: + - "work item" +assignees: + - "shawnalpay" + - "jpradocueva" +body: + - type: markdown + attributes: + value: | + --- + ### **Template Usage Notes**: + 1. All fields marked as **mandatory** [*] must be filled before submission. While some datapoints are optional for the initial creation of the work item, all datapoints must be provided in order to be considered for spec development. + 2. If you have suggestions for the specification but cannot fill out all fields in this issue template, please fill out a [Feedback] or [Discussion] issue template instead. + 3. For **Supporting Documentation**, ensure that linked files are accessible to relevant stakeholders. + + - type: markdown + attributes: + value: | + ## 1. **Problem Statement** + Describe the problem, issue, use case, or opportunity that this work item addresses. + Include practitioner quotes illustrating real examples a) of questions being asked by practitioners and b) value unlocked by answering these questions, if available. + - **What is the problem?**: Explain the context and why it needs resolution. + - **Impact**: Describe how the problem affects users, systems, or the project. + + - type: textarea + id: problem_statement + attributes: + label: "Problem Statement" + description: "Provide a detailed explanation of the problem or issue." + placeholder: "Your input here..." + value: "Provide details of the problem statement here." + validations: + required: true + + - type: markdown + attributes: + value: | + ## 2. **Objective** + State the objective of this work item. What outcome is expected? + - **Success Criteria**: Define how success will be measured (e.g. metrics and KPIs). + + - type: textarea + id: objective + attributes: + label: "Objective" + description: "Describe the expected outcome and success criteria." + placeholder: "Your input here..." + value: "Outline the expected outcome and success criteria." + validations: + required: true + + - type: markdown + attributes: + value: | + ## 3. **Supporting Documentation** + - Data Examples: [Link to data or relevant files; DO NOT share proprietary information] + - Related Use Cases or Discussion Documents: [Link to discussion] + - PRs or Other References: [Link to relevant references] + + - type: textarea + id: supporting_documentation + attributes: + label: "Supporting Documentation" + description: "Provide links to data examples, use cases, PRs, or other relevant documents." + placeholder: "Your input here..." + value: "Include links to supporting documentation, if applicable." + validations: + required: true + + - type: markdown + attributes: + value: | + ## 4. **Proposed Solution / Approach** + Outline any proposed solutions, approaches, or potential paths forward. Do not submit detailed solutions; please keep suggestions high-level. + - **Initial Ideas**: Describe potential solution paths, tools, or technologies. + - **Considerations**: Include any constraints, dependencies, or risks. + - **Feasibility**: Include any information that helps quantify feasibility, such as perceived level of effort to augment the spec, or existing fields in current data generator exports. + - **Benchmarks**: Are there established best practices for solving this problem available to practitioners today (e.g. mappings from existing CSP exports that are widely used)? + + - type: textarea + id: proposed_solution + attributes: + label: "Proposed Solution / Approach" + description: "Outline potential solutions or approaches." + placeholder: "Your input here..." + value: "Summarize the proposed solution or approach." + + - type: markdown + attributes: + value: | + ## 5. **Epic or Theme Association** + > This section will be completed by the Maintainers. + > - **Epic**: [Epic Name] + > - **Theme**: [Theme Name, if applicable] + + - type: textarea + id: epic_theme + attributes: + label: "Epic or Theme Association" + description: "Provide potential epics or themes" + placeholder: "Your input here..." + value: "Provide the rational for the Epic or Theme." + + - type: markdown + attributes: + value: | + ## 6. **Stakeholders** + List the main stakeholders for this issue. + - **Primary Stakeholder**: [Name/Role] + - **Other Involved Parties**: [Names/Roles] + + - type: textarea + id: stakeholders + attributes: + label: "Stakeholders" + description: "List the main stakeholders for this work item." + placeholder: "Your input here..." + value: "Provide names and roles of key stakeholders." diff --git a/CHANGELOG.md b/CHANGELOG.md index 96131dca2..90c970c37 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,13 +5,60 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## v1.1 + +Announced November 2024 + +**Added:** + +- `CapacityReservationId` column +- `CapacityReservationStatus` column +- `CommitmentDiscountQuantity` column +- `CommitmentDiscountUnit` column +- `ServiceSubcategory` column +- `SkuMeter` column +- `SkuPriceDetails` column +- `ProviderVersion` metadata schema property + +**Changed:** + +- `CommitmentDiscountId` column updates: + - Must be globally unique within the provider. + - Should be a fully-qualified identifier. +- `ConsumedQuantity` column updates: + - Must be null when `CommitmentDiscountStatus` is "Unused". +- `ConsumedUnit` column updates: + - Must be null when `ChargeClass` is not "Correction" and `ChargeCategory` is not "Usage". + - Must be null when `ChargeClass` is not "Correction" and `ChargeCategory` is "Usage" and `CommitmentDiscountStatus` is "Unused". + - May be null when `ChargeCategory` is "Usage" and `ChargeClass` is "Correction". +- `EffectiveCost` column updates: + - When `CommitmentDiscountStatus` is "Unused", must be the difference between the used commitment discount amount and the portion of the total commitment discount purchase applicable for the charge period. +- `PricingCategory` column updates: + - Must not be "Committed" when the charge is for a commitment discount purchase. +- `SkuPriceId` column updates: + - `SkuId` can be used if the provider does not have a `SkuPriceId` but other requirements must be met. +- Metadata updates: + - Must be provided in the defined metadata schema. + - Must be an object. + - Must not be null. + - Must include a reference to the schema of the data. + - Schema reference must not be in the FOCUS dataset itself. + - Must be an accurate and complete representation of the provided FOCUS dataset. + - Metadata implementation should be publicly documented. +- `SchemaId` metadata schema property updates: + - Recommended to be a globally unique identifier (GUID) instead of a universally unique identifier (UUID) or SemVer version. + +[All 1.1 changes](https://github.com/FinOps-Open-Cost-and-Usage-Spec/FOCUS_Spec/compare/v1.0...v1.1-cr) + +
+ ## v1.0 Announced June 20, 2024 @@ -25,6 +72,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), - `ContractedUnitPrice` column - `RegionId` column - `RegionName` column +- `DataGenerator` metadata property +- `CreationDate` metadata schema property +- `FocusVersion` metadata schema property +- `SchemaId` metadata schema property +- `ColumnName` metadata column definition property +- `DataType` metadata column definition property +- `NumberScale` metadata column definition property +- `NumberPrecision` metadata column definition property +- `ProviderTagPrefix` metadata column definition property +- `StringEncoding` metadata column definition property +- `StringMaxLength` metadata column definition property **Changed:** @@ -104,7 +162,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), - `ChargeSubcategory` column - See `ChargeCategory` and `ChargeClass` columns -[All 1.0 changes](https://github.com/FinOps-Open-Cost-and-Usage-Spec/FOCUS_Spec/compare/v1.0-preview-cr...1.0-cr) +[All 1.0 changes](https://github.com/FinOps-Open-Cost-and-Usage-Spec/FOCUS_Spec/compare/v1.0-preview...v1.0)
@@ -147,14 +205,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), - `AmortizedCost` column renamed to `EffectiveCost` - `ChargeType` column renamed to `ChargeCategory` -[All 1.0-preview changes](https://github.com/FinOps-Open-Cost-and-Usage-Spec/FOCUS_Spec/compare/v0.5-cr...v1.0-preview-cr) +[All 1.0-preview changes](https://github.com/FinOps-Open-Cost-and-Usage-Spec/FOCUS_Spec/compare/v0.5...v1.0-preview)
## v0.5 + Announced June 24, 2023 **Added:** + - `Column naming convention` attribute - `Currency code format` attribute - `Date/time format` attribute @@ -181,7 +241,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), - `SubAccountId` column - `SubAccountName` column -[All 0.5 changes](https://github.com/FinOps-Open-Cost-and-Usage-Spec/FOCUS_Spec/compare/7106bbe...v0.5-cr) +[All 0.5 changes](https://github.com/FinOps-Open-Cost-and-Usage-Spec/FOCUS_Spec/compare/7106bbe...v0.5)
@@ -199,6 +259,8 @@ This table maps the evolution of the specification, showcasing column introducti | BillingCurrency | 0.5 | | | BillingPeriodEnd | 0.5 | | | BillingPeriodStart | 0.5 | | +| CapacityReservationId | 1.1 | | +| CapacityReservationStatus | 1.1 | | | ChargeType | 0.5 | Renamed to ChargeCategory in v1.0-preview | | ChargeCategory | 1.0-preview | Renamed from ChargeType in v1.0-preview | | ChargeClass | 1.0 | | @@ -212,6 +274,8 @@ This table maps the evolution of the specification, showcasing column introducti | CommitmentDiscountName | 1.0-preview | | | CommitmentDiscountStatus | 1.0 | | | CommitmentDiscountType | 1.0-preview | | +| CommitmentDiscountQuantity | 1.1 | | +| CommitmentDiscountUnit | 1.1 | | | ConsumedQuantity | 1.0 | Renamed from UsageQuantity in v1.0 | | ConsumedUnit | 1.0 | Renamed from UsageUnit in v1.0 | | ContractedCost | 1.0 | | @@ -233,7 +297,10 @@ This table maps the evolution of the specification, showcasing column introducti | ResourceType | 1.0-preview | | | ServiceCategory | 0.5 | | | ServiceName | 0.5 | | +| ServiceSubcategory | 1.1 | | | SkuId | 1.0-preview | | +| SkuMeter | 1.1 | | +| SkuPriceDetails | 1.1 | | | SkuPriceId | 1.0-preview | | | SubAccountId | 0.5 | | | SubAccountName | 0.5 | | diff --git a/EDITORIAL_GUIDELINES.md b/EDITORIAL_GUIDELINES.md new file mode 100644 index 000000000..29e7cbab1 --- /dev/null +++ b/EDITORIAL_GUIDELINES.md @@ -0,0 +1,251 @@ +## Editorial Style Guidelines +The "Editorial Style Guidelines" section ensures consistency and clarity across all documentation. Adhering to these guidelines is crucial for maintaining a unified style, which enhances readability and reduces misinterpretation. By following the specified standards—whether in formatting, linking, or structuring information—we ensure that all documents are professional, clear, and aligned with our editorial principles. Consistent application of these guidelines contributes to high-quality, user-friendly documentation. + +These guidelines can be modified through a Pull Request (PR), which the members must review and agree upon. This process ensures that any changes are thoughtfully considered and maintains the overall integrity of our editorial standards. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ComponentDisplay (PDF, HTML)Markdown (examples)Editorial Guidelines
Column & Attribute Names: + Column Names:
+ - Pricing Quantity
+ - Pricing Unit
+ - Provider

+ Attribute Names:
+ - Currency Code Format
+ - Date/Time Format +
+ Column Names:
+    Pricing Quantity
+    Pricing Unit
+    Provider

+ Attribute Names:
+    Currency Code Format
+    Date/Time Format
+
+ - Use the display name in the non-normative section.
+ - The first occurrence in a section is linked to the section. +
Column & Attribute IDs: + Columns IDs:
+ - PricingQuantity
+ - PricingUnit
+ - ProviderName

+ Attributes IDs:
+ - CurrencyCodeFormat
+ - DateTimeFormat
+
+ Columns IDs:
+    PricingQuantity
+    PricingUnit
+    ProviderName

+ Attributes IDs:
+    CurrencyCodeFormat
+    DateTimeFormat
+
+ - Use PascalCamel case (the first letter of every word, is capitalized)
+ - Normal text without bold or italics.
+ - The first occurrence in a section is linked to the section. +
Column Values: + - "Usage"
+ - "Tax"
+ - "TB"
+
+ This column:
+    * MUST be null when ChargeCategory is "Tax" ... +
+ - Enclosed in double quotation marks
+ - Normal text without bold or italics +
Normative Keywords & Statements + MUST, MAY, MUST NOT and normative statements + + This column:
+    * MUST NOT be null when ChargeClass is ...
+    * MUST be null when ChargeCategory is ...
+    * MAY be null for all other combinations of ...
+
+ - All uppercase, without bold.
+ - Bullet list format.
+
Glossary + SKU, resource, service + + [*SKU*](#glossary:sku)
+ [*resource*](#glossary:resource)
+ [*service*](#glossary:service)
+
+ - Blue font + italic
+ - The first occurrence in a section is linked to the glossary. +
Important Text image> Important Consideration- It is added as a note.
Key-Value FormatJSON Script +
+**Example**:
+```json
+{
+    "key1": "value1",
+    "key2": true,
+    "key3": 123
+}
+```
+            
+
- Monospace font
Tablesimageimage - Tables: Simple tables can be created using markdown, but for more complex tables, it is RECOMMENDED to use HTML elements. See the example below.
+ +**Editorial Notes** +* **Linking Only the First Time**: To prevent excessive linking within sections, Column Name, Column ID, Attributes Names, Attributes IDs, and Glossary will only be linked to their corresponding section or glossary the first time they appear in a section. + +* **Normative Requirements as a Bullet List**: Normative statements (those using Normative Keywords) should be written as bullet points instead of lengthy sentences. + +* **Column IDs:** They SHOULD be used in normative text sections, such as when specifying mandatory rules, schema definitions, or other implementation-related content. These Column IDs should be formatted without spaces and should match the exact naming conventions used in the schema (e.g., CommitmentDiscountID). + +* **Display Names:** They SHOULD be used in introductory or explanatory sections where natural language context is more appropriate. In these sections, display names should follow normal text conventions, including spaces between words (e.g., Commitment Discount ID). + + +### Example + +> **2.28. Pricing Quantity** +> +> The Pricing Quantity represents the volume of a given SKU associated with a [*resource*](#glossary:resource) or [*service*](#glossary:service) used or purchased, based on the [Pricing Unit](#pricingunit). Distinct from [Consumed Quantity](#consumedquantity) (complementary to [Consumed Unit](#consumedunit)), it focuses on pricing and cost, not *resource* and *service* consumption. +> +> * The PricingQuantity column MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset). +> * This column MUST be of type Decimal and MUST conform to [Numeric Format](#numericformat) requirements +> * The value MAY be negative in cases where [ChargeClass](#chargeclass) is "Correction". +> +> This column: +> * MUST NOT be null when [ChargeClass](#chargeclass) is not "Correction" and [ChargeCategory](#chargecategory) is "Usage" or "Purchase", +> * MUST be null when ChargeCategory is "Tax", and +> * MAY be null for all other combinations of ChargeClass and ChargeCategory. +> * When unit prices are not null, multiplying PricingQuantity by a unit price MUST produce a result equal to the corresponding cost metric, except in cases of ChargeClass "Correction", which may address PricingQuantity or any cost discrepancies independently. +> +> **2.28.1. Column ID** +> +> PricingQuantity +> +> **2.28.2. Display Name** +> +> Pricing Quantity +> +> **2.28.3. Description** +> +> The volume of a given SKU associated with a *resource* or *service* used or purchased, based on the Pricing Unit. +> +> **2.28.4. Content Constraints Constraint** +> +> image +> +> **2.28.5. Introduced (version)** +> +> 1.0-preview + +### Example HTML Table +This is an example of a complex table with merged rows and columns, along with an additional header row. + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Heading 1Heading 2Heading 3
Cell 1,1 and Cell 1,2 MergedCell 1,3Cell 1,4
Heading 4Heading 5Heading 6Heading 7
Cell 2,1 & Cell 2,2Cell 3,3
&
Cell 4,3
Cell 3,4
Cell 4,1Cell 4,2Cell 4,4
+ +This is how it is written in HTML: +```html + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Heading 1Heading 2Heading 3
Cell 1,1 and Cell 1,2 MergedCell 1,3Cell 1,4
Heading 4Heading 5Heading 6Heading 7
Cell 2,1 & Cell 2,2Cell 3,3
&
Cell 4,3
Cell 3,4
Cell 4,1Cell 4,2Cell 4,4
+ +``` diff --git a/RELEASE-PLANNING.md b/RELEASE-PLANNING.md index 34b21361f..043128d06 100644 --- a/RELEASE-PLANNING.md +++ b/RELEASE-PLANNING.md @@ -22,6 +22,10 @@ This section outlines the planned release schedule and key milestones for the FO
  • Move beyond the highest-level service categorization to a sub-categorization for services while adding flexibility for providers to share their native categorizations within FOCUS.
  • + Commitment Discount Visibility + Capacity Reservation