Merge pull request #134 from FinOps-Open-Cost-and-Usage-Spec/working_…

…draft

v0.5 Candidate Release

.github/CODEOWNERS

@@ -0,0 +1 @@
+*       @FinOps-Open-Cost-and-Usage-Spec/maintainer

.github/ISSUE_TEMPLATE/discussion-topic.md

@@ -0,0 +1,20 @@
+---
+name: Discussion Topic
+about: Discussion topics that require broader input from FOCUS members
+title: Title of the discussion topic OR open question needing member feedback
+labels: discussion topic
+assignees: ''
+
+---
+
+### Description
+> Describe the discussion topic and/or open topic is. Describe discussion that has taken place and where community feedback is needed. Provide specifics (specially if there are multiple possible options).
+
+### Proposed approach
+> Describe the approach that your group is proposing
+
+### Github issue or Reference
+> If the topic is related to a particular work item, reference the Github issue. If its a specification-wide topic, indicate that.
+
+### Context
+> Add any context that may help the community think through this and provide useful feedback

.github/ISSUE_TEMPLATE/maintenance.md

@@ -0,0 +1,14 @@
+---
+name: Maintenance Task
+about: Tasks that relate to work on the GitHub Repository or GitHub Actions
+title: Repository maintenance task
+labels: repo maintenance
+assignees: ''
+
+---
+
+### Description
+> Description of the issue
+
+### Definition of done
+> Description of the outcome(s) of the maintenance

.github/ISSUE_TEMPLATE/proposal.md

@@ -0,0 +1,17 @@
+---
+name: Proposal
+about: Community proposal to add / enhance the specification
+title: "[Proposal] Title for proposal"
+labels: proposal
+assignees: ''
+
+---
+
+### Type
+> Type of issue (e.g. Dimension, Metric, Attribute, Documentation etc.)
+
+### Proposed Change
+> Description of the issue
+
+### Context / Supporting information
+>Description of the issue

.github/ISSUE_TEMPLATE/spec-change.md

@@ -0,0 +1,26 @@
+---
+name: Spec Change
+about: Spec change issue
+title: Spec Change title
+labels: spec change
+assignees: ''
+
+---
+
+### Type
+> Type of issue (e.g. Dimension, Metric, Attribute, Documentation etc.)
+Normalized? Yes | No
+
+
+### Description
+> Description of the issue
+
+### Definition of done
+
+- [ ] Rationalize vendor-neutral, cross-cloud naming
+- [ ] Complete spec template and include naming (code name, display name), constraints, guidelines, compatibility with major providers etc.
+** If Normalized Dimension **
+- [ ] Include principles and governance criteria for maintaining this dimension
+
+** If Normalized Dimension **
+Work for generating the normalized list of supported values is tracked in a separate issue. Mappings between normalized values and vendor specified values need to be explored as a part of this work. However, these mappings are not included in the spec documentation. Separate tasks will be created for making these mappings available to practitioners outside of the FOCUS repository.

.github/workflows/candidate_release.yml

@@ -0,0 +1,37 @@
+name: generate_candidate_release_spec
+on:
+  push:
+    branches:
+      - 'candidate_release'
+
+jobs:
+    # The job that will use the container image you just pushed to ghcr.io
+    gen_pdf:
+        runs-on: ubuntu-20.04
+        container:
+            image: pandoc/extra:latest-ubuntu
+        steps:
+            - name: Check out repository code
+              uses: actions/checkout@v3
+            - name: Install prequirements
+              shell: bash
+              run: |
+                /usr/bin/apt-get -y update
+                wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6.1-2/wkhtmltox_0.12.6.1-2.jammy_amd64.deb
+                DEBIAN_FRONTEND=noninteractive /usr/bin/apt install -y make
+                DEBIAN_FRONTEND=noninteractive /usr/bin/apt install -y -f ./wkhtmltox_0.12.6.1-2.jammy_amd64.deb
+                /usr/bin/pip3 install -r requirements.txt
+            - name: Build PDF
+              shell: bash
+              working-directory: ./specification
+              run: |
+                make STYLE=candidate_release
+            - name: Upload Spec
+              uses: actions/[email protected]
+              with:
+                name: FOCUS_specification
+                path: |
+                  specification/spec.html
+                  specification/spec.pdf
+                  specification/images/*
+                  specification/styles/*

.github/workflows/main.yml

@@ -0,0 +1,37 @@
+name: generate_publication_spec
+on:
+  push:
+    branches:
+      - 'main'
+
+jobs:
+    # The job that will use the container image you just pushed to ghcr.io
+    gen_pdf:
+        runs-on: ubuntu-20.04
+        container:
+            image: pandoc/extra:latest-ubuntu
+        steps:
+            - name: Check out repository code
+              uses: actions/checkout@v3
+            - name: Install prequirements
+              shell: bash
+              run: |
+                /usr/bin/apt-get -y update
+                wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6.1-2/wkhtmltox_0.12.6.1-2.jammy_amd64.deb
+                DEBIAN_FRONTEND=noninteractive /usr/bin/apt install -y make
+                DEBIAN_FRONTEND=noninteractive /usr/bin/apt install -y -f ./wkhtmltox_0.12.6.1-2.jammy_amd64.deb
+                /usr/bin/pip3 install -r requirements.txt
+            - name: Build PDF
+              shell: bash
+              working-directory: ./specification
+              run: |
+                make STYLE=main
+            - name: Upload Spec
+              uses: actions/[email protected]
+              with:
+                name: FOCUS_specification
+                path: |
+                  specification/spec.html
+                  specification/spec.pdf
+                  specification/images/*
+                  specification/styles/*

.github/workflows/working_draft.yml

@@ -0,0 +1,39 @@
+name: generate_draft_spec
+on:
+  push:
+    branches:
+      - '*'
+      - '!main'
+      - '!candidate_release'
+
+jobs:
+    # The job that will use the container image you just pushed to ghcr.io
+    gen_pdf:
+        runs-on: ubuntu-20.04
+        container:
+            image: pandoc/extra:latest-ubuntu
+        steps:
+            - name: Check out repository code
+              uses: actions/checkout@v3
+            - name: Install prequirements
+              shell: bash
+              run: |
+                /usr/bin/apt-get -y update
+                wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6.1-2/wkhtmltox_0.12.6.1-2.jammy_amd64.deb
+                DEBIAN_FRONTEND=noninteractive /usr/bin/apt install -y make
+                DEBIAN_FRONTEND=noninteractive /usr/bin/apt install -y -f ./wkhtmltox_0.12.6.1-2.jammy_amd64.deb
+                /usr/bin/pip3 install -r requirements.txt
+            - name: Build PDF
+              shell: bash
+              working-directory: ./specification
+              run: |
+                make STYLE=working_draft
+            - name: Upload Spec
+              uses: actions/[email protected]
+              with:
+                name: FOCUS_specification
+                path: |
+                  specification/spec.html
+                  specification/spec.pdf
+                  specification/images/*
+                  specification/styles/*

.gitignore

@@ -0,0 +1,6 @@
+*.pdf
+.DS_Store
+spec.md
+spec.html
+*.pyc
+specification/version.md

LICENSE.txt

@@ -0,0 +1 @@
+TBC

README.md

@@ -1 +1,70 @@
-# FOCUS_Spec
+# FinOps Open Cost and Usage Specification (FOCUS) - Specification Working Group
+
+The Open Cloud Bill working group will develop a common, source-neutral schema of
+billing, cost, usage, and observability data mapped to a variety of cloud service provider and SaaS product
+sources, with metadata, dimensions, metrics, and measures for the source and common schema fields. As per the [Working Group Chater]() **Link TBC**
+
+## Notation Conventions and Compliance
+
+The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
+"SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in the
+[specification][] are to be interpreted as described in [BCP
+14](https://tools.ietf.org/html/bcp14)
+[[RFC2119](https://tools.ietf.org/html/rfc2119)]
+[[RFC8174](https://tools.ietf.org/html/rfc8174)] when, and only when, they
+appear in all capitals, as shown here.
+
+An implementation of the [specification][] is not compliant if it fails to
+satisfy one or more of the "MUST", "MUST NOT", "REQUIRED", "SHALL", or "SHALL
+NOT" requirements defined in the [specification][]. Conversely, an
+implementation of the [specification][] is compliant if it satisfies all the
+"MUST", "MUST NOT", "REQUIRED", "SHALL", and "SHALL NOT" requirements defined in
+the [specification][].
+
+## Versioning the Specification
+
+Changes to the [specification](./specification/overview.md) are versioned according to [Semantic Versioning 2.0](https://semver.org/spec/v2.0.0.html) and described in [CHANGELOG.md](CHANGELOG.md). Layout changes are not versioned. Specific implementations of the specification should specify which version they implement.
+
+## Project Naming
+
+- The official project name is "FinOps Open Cost and Usage Specification"
+- The official acronym used by the FinOps Open Cost and Usage Specification project is "FOCUS"
+- While the official acronym includes the word "Specification", it is still acceptable to refer to this working groups output as the "FOCUS Specification"
+
+## About the project
+
+See the [project repository](https://github.com/FinOps-Open-Cost-and-Usage-Spec/foundation) for information about the following, and more:
+
+- [Change / contribution process](https://github.com/FinOps-Open-Cost-and-Usage-Spec/foundation/blob/main/contributing.md)
+
+## FOCUS Specification Development Environment
+
+Most people will not need any development environment, it is mostly needed by the FinOps Foundation staff members who maintain the FOCUS Repositories and associated document build pipelines. Currently, the only tested (supported) environment is a MacOS setup, however the build pipeline in GitHub uses Ubuntu so should be possible to run on a Linux environment.
+
+### Setup Steps
+
+1. Install homebrew (as per: https://brew.sh)
+2. Setup cask
+
+	`brew install cask`
+3. Install python
+
+	`brew install python`
+4. Add packages for python
+
+	`pip3 install -r requirements.txt`
+5. Install pandoc and required filter library
+
+	`brew install pandoc`
+
+	`brew install --cask wkhtmltopdf`
+6. If your machine does not have git/make etc, you might fun the following: Install developer command line tools for MacOS 
+
+	`xcode-select --install`
+
+### Assembling the specification locally
+
+1. Move into the `specification` folder
+2. Use make to generate the spec `make`
+
+[specification]: specification/specification-overview.md

custom_linter_rules/rule_md_990.py

@@ -0,0 +1,75 @@
+"""
+Module to implement a plugin that looks for smart characters in the files.
+"""
+from typing import cast
+
+from pymarkdown.inline_markdown_token import TextMarkdownToken
+from pymarkdown.markdown_token import MarkdownToken
+from pymarkdown.parser_helper import ParserHelper
+from pymarkdown.plugin_manager.plugin_details import PluginDetails
+from pymarkdown.plugin_manager.plugin_scan_context import PluginScanContext
+from pymarkdown.plugin_manager.rule_plugin import RulePlugin
+
+
+class RuleMd990(RulePlugin):
+    """
+    Class to implement a plugin that looks for smart characters in the files.
+    """
+    __smart_char_items = [u"\u2013", u"\u201c", u"\u201d", u"\u2018", u"\u2019", u"\u2026"]
+
+    def __init__(self) -> None:
+        super().__init__()
+
+    def get_details(self) -> PluginDetails:
+        """
+        Get the details for the plugin.
+        """
+        return PluginDetails(
+            plugin_name="no-smart-characters",
+            plugin_id="MD990",
+            plugin_enabled_by_default=True,
+            plugin_description="Smart character found",
+            plugin_version="0.1.0",
+            plugin_interface_version=1,
+            plugin_url="",
+        )
+
+    def next_token(self, context: PluginScanContext, token: MarkdownToken) -> None:
+        """
+        Event that a new token is being processed.
+        """
+        if (
+            token.is_text
+        ):
+            text_token = cast(TextMarkdownToken, token)
+            for smart_char_item in RuleMd990.__smart_char_items:
+                start_index = 0
+                found_index = text_token.token_text.find(smart_char_item, start_index)
+                while found_index != -1:
+                    (
+                        column_number_delta,
+                        line_number_delta,
+                    ) = ParserHelper.adjust_for_newlines(text_token.token_text, 0, found_index)
+                    self.report_next_token_error(
+                        context,
+                        token,
+                        line_number_delta=line_number_delta,
+                        column_number_delta=column_number_delta,
+                    )
+                    start_index = found_index + len(smart_char_item)
+                    found_index = text_token.token_text.find(smart_char_item, start_index)
+
+
+        elif token.is_code_block:
+            self.__in_code_block = True
+        elif token.is_code_block_end:
+            self.__in_code_block = False
+        elif token.is_html_block:
+            self.__in_html_block = True
+        elif token.is_html_block_end:
+            self.__in_html_block = False
+        elif token.is_inline_link:
+            self.__in_link = True
+        elif token.is_inline_link_end:
+            self.__in_link = False
+

requirements.txt

@@ -0,0 +1,2 @@
+watchdog==3.0.0
+pymarkdownlnt==0.9.11

scope.md

@@ -0,0 +1,5 @@
+FOCUS Specification Working Group Scope
+---------------------------------------
+
+
+The scope of this working group can be found in the [CLA](https://github.com/FinOps-Open-Cost-and-Usage-Spec/foundation/blob/main/FOCUS_-_Membership_Agreement_Package_for_use.pdf)

spec-design-guidelines.md

@@ -0,0 +1,25 @@
+Guidelines for Specification Design
+-----------------------------------
+
+When designing and creating the document for the specification, the following guidelines should be adhered to.
+
+Specification Content
+---------------------
+
+The specification:
+* must not specify that a specific technology, software package/library, or cloud provider must be (or is recommended to be) used
+* can use examples that show a specific technology, software package/library, or cloud provider to demonstrate a concept
+* should use lots of figures and examples to help visualize the content of the specification
+* must keep figures and examples close to the normative prose
+* must not rely on figures to define the specification, normative prose is always required to make precise specifications
+
+
+Document Design
+--------------
+
+The specification content:
+* must have a Table of Contents which makes sense and the ordering of content should be sensical, headings should help people identify the section they are looking for
+* must be written with an overall model before digging into the details. Each section will start with an overview of the feature and description
+* should be written in order, so when read top to bottom any referenced content has already been covered in a previous section
+
+Some of these items have been formed based on this W3C video on [Best Pracitices for Editing W3C Specifications](https://www.youtube.com/watch?v=FdB8mqlf1l8)