Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Editorial changes to columns names and ids (part 2) #589

Merged
merged 8 commits into from
Oct 8, 2024
Merged

Editorial changes to columns names and ids (part 2) #589

merged 8 commits into from
Oct 8, 2024

Conversation

ijurica
Copy link
Contributor

@ijurica ijurica commented Oct 5, 2024 •
edited
Loading

The changes in this PR are in accordance with the agreement that we will continue to use the previous version of the editorial guidelines in FOCUS version 1.1 (for details, see the table below).

Component Markdown (examples) Editorial Guidelines
Column Names: Column Names:
Pricing Quantity
Pricing Unit
Provider
  • Normal text without bold or italics.
  • Use the display name in the introductory (non-normative) section and description.
  • The first occurrence in a section is linked to the section, except when referring to itself.
Attribute Names: Attribute Names:
Currency Code Format
Date/Time Format
  • Normal text without bold or italics.
  • Use the attribute display name in the introductory (non-normative) section, description, normative section, and content constraints table.
  • The first occurrence in a section is linked to the section, except when referring to itself.
Column IDs: Column IDs:
PricingQuantity
PricingUnit
ProviderName
  • Normal text without bold or italics.
  • Use the column ID in the normative section and when referencing column values.
  • For column IDs, use PascalCase (the first letter of every word is capitalized).
  • The first occurrence in a section is linked to the corresponding column, except when referring to itself.
Glossary [*SKU*](#glossary:sku)
[*resource*](#glossary:resource)
[*service*](#glossary:service)
  • Italic.
  • The first occurrence in a section is linked to the glossary term.

Types of Editorial Changes:

  • Aligned the formatting of references to columns (display name, ID) and glossary terms with the approach used in other columns.
  • Aligned formatting of references to format attributes in normative requirements, opting for the attribute name instead of the attribute ID (see Note for reasoning):
  • Addressed several missing and broken links to columns and glossary terms.

Changes applied to the following columns:

  • Commitment Discount Quantity
  • Commitment Discount Unit
  • Consumed Unit
  • Pricing Unit
  • Service Subcategory

Notes:

  • I prefer using the attribute name over the attribute ID when referencing formatting attributes, at least for now, considering:

    • The attribute name was used in the Content Constraints tables in all instances.
    • The attribute name was used in the Normative Requirements in 13 instances.
    • The attribute ID was used in the Normative Requirements in only 4 instances (CommitmentDiscountUnit, ConsumedUnit, PricingUnit, SkuPriceDetails).

  • In 2 instances (ChargePeriodStart and ChargePeriodEnd), although listed in the constraints table, the requirement to follow the Date/Time format wasn’t explicitly mentioned in the normative requirements paragraph. I suggest addressing all Date/Time references in version 1.2 or later.

@ijurica
CommitmentDiscountUnit, CommitmentDiscountQuantity, ConsumedUnit, Pri…
b5c18ba 
…cingUnit - link to glossary fix and editorial cleanup (column names and ids)
@ijurica ijurica requested a review from a team as a code owner October 5, 2024 10:46
@ijurica ijurica self-assigned this Oct 5, 2024
@ijurica ijurica added consistency/review Consistency Review editorial Items that address editorial and minor changes labels Oct 5, 2024
@ijurica ijurica mentioned this pull request Oct 6, 2024
Merged
@ijurica ijurica mentioned this pull request Oct 7, 2024
Merged
@jpradocueva
Copy link
Contributor

Action Items from Maintainers' call on Oct 7:

  • [TF1-#589] Maintainers: Validate the corrections and verify that references match the new format.

@jpradocueva jpradocueva added this to the v1.1 milestone Oct 8, 2024
jpradocueva
jpradocueva approved these changes Oct 8, 2024
View reviewed changes
Copy link
Contributor

@jpradocueva jpradocueva left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ready to merge.

@jpradocueva
Copy link
Contributor

Approved during the Members' call on Oct 8.

@jpradocueva jpradocueva merged commit 5f123bd into working_draft Oct 8, 2024
2 checks passed
@jpradocueva jpradocueva deleted the editorial-columns-names-ids-p2 branch October 8, 2024 22:49
jpradocueva added a commit that referenced this pull request Oct 8, 2024
@ijurica @jpradocueva
Editorial changes: using attribute IDs when referencing attributes in…
31276dd 
… normative paragraphs (#593)

**Type of Editorial change:**

Although attribute names were initially used for this purpose, for the
sake of consistency and in accordance with the agreement made during the
maintainers' meeting on Oct 8th, **switching from attribute names to
attribute IDs in the normative paragraphs**, while retaining attribute
names in the Content Constraints tables.

**Scope of this PR:**

This PR addresses references in the normative paragraphs of 12 columns
and Metadata - CreationDate.
For the remaining column, CommitmentDiscountQuantity, please refer to PR
#589.

---------

Co-authored-by: Joaquin <[email protected]>
jpradocueva added a commit that referenced this pull request Oct 8, 2024
@ijurica @jpradocueva
Editorial changes - links to FOCUS dataset glossary term (#592)
c6fb404 
Editorial changes:

- Replaced ...MUST be present in the billing data... with ...MUST be
present in a **[*FOCUS dataset*](#glossary:FOCUS-dataset)**... in the
following columns:
  - CapacityReservation
  - ChargeClass
  - ConsumedUnit
  - SkuMeter

- Added **links to the FOCUS dataset glossary term** for the remaining
columns and other instances where the FOCUS dataset is mentioned.

---

**Note:** For three columns, there are concurrent editorial PRs
addressing column ID formatting and making changes to the same code
line. To simplify the merge process and avoid conflicts, **links to the
FOCUS dataset term** are not included in this PR but have been **added
as suggestions in the respective PRs**:

- SKU Price Details (see PR #588)
- SKU Price ID (see PR #588)
- Pricing Unit (see PR #589)

---------

Co-authored-by: Joaquin <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@udam-f2 udam-f2 udam-f2 approved these changes

@cnharris10 cnharris10 cnharris10 approved these changes

@jpradocueva jpradocueva jpradocueva approved these changes

@shawnalpay shawnalpay Awaiting requested review from shawnalpay

Assignees

@ijurica ijurica

Labels
consistency/review Consistency Review editorial Items that address editorial and minor changes
Projects
FOCUS WG
Status: W.I.P
Milestone
v1.1
Development

Successfully merging this pull request may close these issues.
4 participants
@ijurica @jpradocueva @cnharris10 @udam-f2