…arately from consumed quantity/unit columns (#400)

**Lead Maintainers**: Chris Harris, @cnharris10, Irena Jurica, @ijurica
### Documents: 
* **PR**:
[#400](#400)
Commitment Utilization and Normalization
* **PR**:
[#524](#524)
rename Commitment-Based Discount to Commitment-Discount by
[[email protected]](mailto:[email protected])
* [Usage vs Pricing Quantity and unit
examples](https://docs.google.com/spreadsheets/d/1zA0brhrEntfWlzt5VNcNLBFnKPEiarajTF84o4ATeEw/edit?gid=1705742856#gid=1705742856)
*
[24.07.21-CommitmentUtilization-sample-datasets](https://docs.google.com/spreadsheets/d/1AYDPZ4rl90PPEbyQJUaGCUSwZ4s_sfy-8sO2KyNq0aM/edit?usp=drive_link)
*
[#400-commitment-utilization](https://drive.google.com/drive/u/0/folders/1u4_rc6TAqgMwuIQEKUVIX3zAzyvLM7Dj)
folder
* Document: [24.09.08 - Commitment utilization
discussion](https://docs.google.com/document/d/1bOD6MYoFi0fX-MgLyN-hxUpNOSfojlsL0MSt3menOxk/edit?usp=sharing)
* **Slack channel**:
[#tf-commitment-utilization](https://f2-focus.slack.com/archives/C07CPAQDN75)
* Approval deadline: ~Aug 29~, Sep 5


# Related PR's (Appendices):
- #528
- #535

# Key Points
- Adds 3 new columns to track CSP usage-based and spend-based
commitments: `CommitmentDiscountConsumedQuantity`,
`CommitmentDiscountPurchasedQuantity`, `CommitmentDiscountUnit`
- `CommitmentDiscountConsumedQuantity` captures the commitment units
used or unused in a charge period.
- `CommitmentDiscountPurchasedQuantity` captures the commitment units
purchased for one-time and recurring charge periods.
- `CommitmentDiscountUnit` captures the unit that the commitment
discount specifies.
- Fixes a 1.0 bug by specifying that `ConsumedQuantity` and
`ConsumedUnit` MUST be NULL for unused commitment rows. (reference
[pr](#507))
- Further scopes the definition of `commitment discount` and `negotiated
discount` within the glossary and specifies that `CommitmentDiscount*`
columns only correspond to `commitment discounts`.

## UPDATE (8/16/24)
1. Columns renamed to: `CommitmentDiscountConsumedQuantity`,
`CommitmentDiscountUnit`, `CommitmentDiscountPurchaseQuantity`
2. `{List,Contracted}UnitPrice`, `Pricing{Quantity,Unit}` are null when
`CommitmentDiscountStatus:Unused`
3. `{List,Contracted}Cost` are 0 when `CommitmentDiscountStatus:Unused`
4. New, official glossary terms incorporated from FinOps page for
[`commitment-based
discount`](https://www.finops.org/assets/terminology/#commitment-discounts)
and [`negotiated
discount`](https://www.finops.org/assets/terminology/#cloud-cost-management-terminology)

## UPDATE (8/19/24)
1. `{List,Contracted}{Cost,UnitPrice}` and `Pricing{Quantity,Unit}`
columns now `0` or `null` when `CommitmentDiscountStatus:Unused` (TO BE
DISCUSSED in TF-1)
2. `{List,Contracted}{Cost,UnitPrice}` and `Pricing{Quantity,Unit}`
columns now in bullet-list format.
3. Correction-based normative text added by Irena.
4. This
[pr](#524)
exists to renaming all instances of
`/commitment[\-,\s]?based\sdiscount/i` to `commitment discount` (with
correct casing)

### Discussion Points (8/20/24)
1. 2 current views for columns: `{List,Contracted}{Cost,UnitPrice}` and
`Pricing{Quantity,Unit}` when `CommitmentDiscountStatus:Unused`
    a. Set all values to appropriate `null` or `0` values (current).
b. Set all values to the same values as the purchase record (if it
exists).
2. Currently, `PricingCategory MUST be "Committed" when
[CommitmentDiscountId](#commitmentdiscountid) is not null`. Should this
be changed to `Standard` for `Purchase` rows where the
`CommitmentDiscountId` is the `ResourceId`?
3. With commitment/negotiated discount definitions altered, is it clear
that current/planned `CommitmentDiscount*` columns are relevant for
commitment discounts and *not* negotiated discounts?

## UPDATE (8/21/24)
1. Includes a recurring purchase for each charge period of the term for
No/Partial Upfront commitments
- No Upfront Purchase - has all units for the charge period
- Partial Upfront Purchase - has 1/2 of the units for each charge period
2. Reverts changing guidance around these
`{List,Contracted}{Cost,UnitPrice}` and `Pricing{Quantity,Unit}`
columns.
3. Adds additional guidance commitment discount purchase is one-time vs.
recurring
4. Adds additional phrasing to differentiate commitment vs negotiated
discounts in each CommitmentDiscount* column.
5. Removes edit to resource name to further minimize pr size (for now)

## Update (8/22/24)
1. Changes to the ResourceId column have been reverted (no clause for
ResourceId to be null with an unused commitment discount)

## Update (8/31/24)
Given that this pr was not fully approved on 8/30, and there was
considerable feedback (but less time) to merge
`CommitmentDiscountConsumedQuantity` and
`CommitmentDiscountPurchasedQuantity` into 1 column, I've gone ahead
with this change to form column: `CommitmentDiscountQuantity`.

Practitioners can stil filter to purchases and committed usage like:
- Purchases: `ChargeCategory = 'Purchase' AND CommitmentDiscountId IS
NOT NULL`
- Committed Usage (Used): `ChargeCategory = 'Usage' AND
CommitmentDiscountStatus = 'Used' AND CommitmentDiscountId IS NOT NULL`
- Committed Usage (Unused): `ChargeCategory = 'Usage' AND
CommitmentDiscountStatus = 'Unused' AND CommitmentDiscountId IS NOT
NULL`.

## Update (9/3/24)
- Added a brief paragraph around size-flexibility within
`CommitmentDiscountQuantity`
- Added additional glossary terms: `size-flexibility`,
`instance-family`, `instance-type`, `instance-type-ratio`.
- `instance-type-ratio` is the proposal for a generic, "FOCUS" term for
`normalization factor` (AWS), or `size flexibility ratio` (Azure)

This change is meant to reduce the number of proposed columns *without*
changing *any* (meaningful) intent of the previous versions with 2
quantity columns. The last commit to this pr encapsulates this entire
change and can be backed out if the group does not approve of this
iteration.

## Update (9/10/24)
- Further generalize "size-flexibility" as "commitment flexibility" and
tie to provider requirements
- Further generalize unit suggestions

# Sample Data

https://docs.google.com/spreadsheets/d/1AYDPZ4rl90PPEbyQJUaGCUSwZ4s_sfy-8sO2KyNq0aM/edit?pli=1&gid=1976106562#gid=1976106562

# Normative Text (original version, adopted into pr)


https://docs.google.com/spreadsheets/d/1AYDPZ4rl90PPEbyQJUaGCUSwZ4s_sfy-8sO2KyNq0aM/edit?pli=1&gid=464941124#gid=464941124

---------

Co-authored-by: Irena Jurica <[email protected]>
Co-authored-by: Udam Dewaraja <[email protected]>
Co-authored-by: Graham <[email protected]>
Co-authored-by: Larry Advey <[email protected]>
Co-authored-by: Michael Flanakin <[email protected]>