Implement proposed reporting requirements from discussion 103

Software_Carbon_Intensity/Appendix_A_Further_Information_on_Reporting_Requirements.md

@@ -0,0 +1,93 @@
+# Appendix A: Further information on Reporting Requirements
+This appendix provides additional detail on validly formed machine-readable SCI reporting files, in YAML format.
+
+## File Structure
+
+To comply with this specification and implement carbon transparency, an entity MUST meet these reporting requirements. The hierachical structure of the YAML file is described below.
+
+### Data elements to be reported
+The following list contains the REQUIRED and OPTIONAL data elements to be reported.
+
+| Name | Identifier | Optionality | Format | Notes |
+| - | - | - | - | - |
+| Supporting infrastructure and systems contained within the [Software Boundary](Software_Carbon_Intensity_Specification#software-boundary) | sci/software-boundary | MUST | Text | A description of the software boundary for the entity. |
+| [Software Carbon Intensity](Software_Carbon_Intensity_Specification#reporting-the-sci-value) - `SCI`| sci/sci | MUST | Numeric | The [Software Carbon Intensity](Software_Carbon_Intensity_Specification#reporting-the-sci-value) of the entity itself.
+| [Software Carbon Intensity](Software_Carbon_Intensity_Specification#reporting-the-sci-value) - `R` baseline value | sci/r | MUST | Numeric |
+| [Software Carbon Intensity](Software_Carbon_Intensity_Specification#reporting-the-sci-value) - `R` baseline source| sci/r-source | MUST | Text | The text CAN refer to one of the identifiers in the [pre-set list](Software_Carbon_Intensity_Specification#preset-list-for-baselines), but it can also refer to a similar concept. |
+| Product Name, entity name, or Software Product | metadata/name | MUST | Text | |
+| Contact name | metadata/contact-name | MUST | Text | The point of contact responsible and accountable for the report. |
+| Contact email | metadata/contact-email | MUST | Text | The point of contact responsible and accountable for the report. |
+| Organization | metadata/organization | SHOULD | Text | This SHALL be populated where the report is not by an individual contributor, otherwise it is not required. |
+| GUID | metadata/guid | MUST | GUID | Following a format in [RFC4122], provided to uniquely identify this particular product, resource, or service. |
+| Software or Product Version | metadata/entity-version | MUST | Text | |
+| SCI Specification Version | metadata/sci-version | MUST | Numeric | The version of the SCI specification against which this report is being made. |
+| Date of Calculation | metadata/calculation-date | MUST | Date | Following a format described in [RFC3339], [a subset](https://ijmacd.github.io/rfc3339-iso8601/) of ISO 8601 |
+| Further information on calculation | metadata/calculation-information | MAY | Text | More information on your calculation methodology can be provided as freetext, or as a URL to an external document or software repository. |
+| Further information on report | metadata/report-information-url | MAY | URL | More information on your calculation methodology MAY be provided, and this MUST be a URL to an external document or software repository.  |
+
+## YAML File Example
+
+### 1. Generic Example without an additional report
+File name: `25c78b6d-b049-424d-87c1-28f07e41bb23/report.yaml`
+
+```yaml
+sci:
+  software-boundary: 'The software boundary of this report is limited to a single markdown file, as it is provided for example only.'
+  sci: 0.5
+  r: 1
+  r-source: machine-learning-baseline
+metadata:
+  name: Example Report
+  contact-name: Responsible Point of Contact
+  contact-email: [email protected]
+  organization: GSF
+  guid: 25c78b6d-b049-424d-87c1-28f07e41bb23
+  entity-version: '0.1'
+  sci-version: 1.0
+  calculation-date: '2021-10-20'
+  calculation-information: 'https://github.com/Green-Software-Foundation/software_carbon_intensity'
+
+```
+### 2. Generic Example with an additional report
+File name: `25c78b6d-b049-424d-87c1-28f07e41bb23/report.yaml`
+
+```yaml
+sci:
+  software-boundary: 'The software boundary of this report is limited to a single markdown file, as it is provided for example only.'
+  sci: 0.5
+  r: 1
+  r-source: machine-learning-baseline
+metadata:
+  name: Example Report
+  contact-name: Responsible Point of Contact
+  contact-email: [email protected]
+  organization: GSF
+  guid: 25c78b6d-b049-424d-87c1-28f07e41bb23
+  entity-version: '0.1'
+  sci-version: 1.0
+  calculation-date: '2021-10-20'
+  calculation-information: 'https://github.com/Green-Software-Foundation/software_carbon_intensity'
+  report-information-url: 'https://github.com/Green-Software-Foundation/software_carbon_intensity'
+
+```
+
+### 3. Generic Example by an individual contributor
+File name: `25c78b6d-b049-424d-87c1-28f07e41bb23/report.yaml`
+
+```yaml
+sci:
+  software-boundary: 'The software boundary of this report is limited to a single markdown file, as it is provided for example only.'
+  sci: 0.5
+  r: 1
+  r-source: machine-learning-baseline
+metadata:
+  name: Example Report
+  contact-name: Individual Point of Contact
+  contact-email: [email protected]
+  guid: 25c78b6d-b049-424d-87c1-28f07e41bb23
+  entity-version: '0.1'
+  sci-version: 1.0
+  calculation-date: '2021-10-20'
+  calculation-information: 'https://github.com/Green-Software-Foundation/software_carbon_intensity'
+
+```

Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md

@@ -18,7 +18,7 @@ Alpha signals that we are ready for early feedback, that this is not the final v
 
 The Software Carbon Intensity (SCI) Specification defines a methodology for calculating the rate of carbon emissions for a software system. The purpose is to help users and developers make informed choices about which tools, approaches, architectures, and services they use in the future. It is a score rather than a total; lower numbers are better than higher numbers, and reaching 0 is impossible.
 
-The SCI is for everyone. It is possible to calculate an SCI score for any software application, from a large distributed cloud system to a small monolithic open source library, any on-premise application or even a serverless function. The product or service may be running in any environment, whether a personal computer, private data center or a hyperscale cloud. 
+The SCI is for everyone. It is possible to calculate an SCI score for any software application, from a large distributed cloud system to a small monolithic open source library, any on-premise application or even a serverless function. The product or service may be running in any environment, whether a personal computer, private data center or a hyperscale cloud.
 
 Reducing an SCI score is only possible through changes to a software system to use less physical hardware, less energy, or consume lower-carbon energy sources. Neutralisations such as carbon offsets do not reduce an SCI score ([see exclusions section](#exclusions)).
 
@@ -58,9 +58,9 @@ Where:
 
 - `M` = Embodied emissions of a software system
 
-- `R` = Functional unit (e.g. carbon per additional user, API-call, ML job, etc) 
+- `R` = Functional unit (e.g. carbon per additional user, API-call, ML job, etc)
 
-The equation can be further refined to 
+The equation can be further refined to
 
 `SCI = (O + M) per R`
 
@@ -76,14 +76,14 @@ Where:
 
 - `C = O + M` = Amount of carbon the software is emitting.
 
-### Operational Emissions  (`O`) 
-To calculate the operational emissions associate with software, multiply the electricity consumption of the hardware the software is running on by the regional, granular marginal emissions rate. The marginal emissions rate reflects the change in emissions associated with a change in demand. 
+### Operational Emissions  (`O`)
+To calculate the operational emissions associate with software, multiply the electricity consumption of the hardware the software is running on by the regional, granular marginal emissions rate. The marginal emissions rate reflects the change in emissions associated with a change in demand.
 
 #### Energy (`E`)
 
 This is the energy consumed by a software system for a functional unit of work. This MUST be in kilowatt hours (kWh).
 
-This could be applied to several taxonomies:  
+This could be applied to several taxonomies:
 
 - Datacenter
 - Individual machine (e.g. VM/Node)
@@ -104,9 +104,9 @@ The only figure that matters if you’re trying to optimize the scheduling of yo
 
 ### Embodied Emissions (`M`)
 
-Embodied carbon (otherwise referred to as “Embedded Carbon”) is the amount of carbon emitted during the creation and disposal of a hardware device. 
+Embodied carbon (otherwise referred to as “Embedded Carbon”) is the amount of carbon emitted during the creation and disposal of a hardware device.
 
-When software runs on a device, a fraction of the total embodied emissions of the device is allocated to the software. This is the value of `M` that you need to calculate in the SCI equation. 
+When software runs on a device, a fraction of the total embodied emissions of the device is allocated to the software. This is the value of `M` that you need to calculate in the SCI equation.
 
 This fraction consists of both a time-share and a resource-share. The length of time your software runs on the device determines the time-share. The percentage of the device reserved just for your application during the time-share determines your resource-share.
 
@@ -190,7 +190,7 @@ A suggested list of functional units includes:
 
 The third step in generating your SCI score is deciding the approach to take when quantifying the carbon emissions for *each component* in your software boundary.
 
-The goal of the SCI is to **quantify** how much `C` (carbon) is emitted per **one unit** of `R`. 
+The goal of the SCI is to **quantify** how much `C` (carbon) is emitted per **one unit** of `R`.
 
 There are two main approaches to quantifying carbon emissions (`C`), [measurement](#measurement) via real-world data or [calculation](#calculation) via models.
 
@@ -208,7 +208,7 @@ You MAY model what one unit of `R` looks like and calculate the total carbon (`C
 
 ## Comparing a SCI Score to a Baseline
 
-When taking an action to reduce the carbon intensity of a piece of software, the intensity SHOULD be compared to a baseline. The baseline MUST be calculated using an identical methodology to how the proposed SCI was calculated, except excluding the proposed action(s). The measurements, assumptions, models, functional unit, etc. MUST remain the same between the baseline and proposed SCI.  
+When taking an action to reduce the carbon intensity of a piece of software, the intensity SHOULD be compared to a baseline. The baseline MUST be calculated using an identical methodology to how the proposed SCI was calculated, except excluding the proposed action(s). The measurements, assumptions, models, functional unit, etc. MUST remain the same between the baseline and proposed SCI.
 
 ## Core Characteristics
 
@@ -222,7 +222,7 @@ As the SCI specification matures and develops, these core characteristics MUST r
 ### The SCI takes a systems-impact view
 
 - The purpose of the SCI is to encourage actions that reduce carbon emissions of software in a way that create reductions at a system-wide level rather than just at a local level. Local level optimizations MAY lead to micro-improvements but MAY have negative downstream impacts at a macro-level that negate the impact of those actions.
-- Such a systems view MUST be adopted by articulating the [boundaries](#boundaries) of the software and its associated infrastructure, keeping in mind the [exclusions](#exclusions) mentioned in this specification. 
+- Such a systems view MUST be adopted by articulating the [boundaries](#boundaries) of the software and its associated infrastructure, keeping in mind the [exclusions](#exclusions) mentioned in this specification.
 
 ### The SCI is easy to implement