Approved SCI moved to Main (#332)

* Added template for case studies * Update Software_Carbon_Intensity/case_study_template.md Co-authored-by: Asim Hussain <[email protected]> * Update Software_Carbon_Intensity/case_study_template.md Co-authored-by: Asim Hussain <[email protected]> * Update Software_Carbon_Intensity/case_study_template.md Co-authored-by: Asim Hussain <[email protected]> * Implement proposed reporting requirements from discussion 103 (#123) * Add first pass of text * Add reference to RFC4122 * Added description of valid requirements * Added first examples * Grammar review * Remove JSON * Move table structure to appendix * Remove reporting process * Changed software boundary reporting requirements * Removed other references to reports * updated URLs * Update Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md Co-authored-by: Asim Hussain <[email protected]> * Update Software_Carbon_Intensity/Appendix_A_Further_Information_on_Reporting_Requirements.md Co-authored-by: Asim Hussain <[email protected]> * Update Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md Co-authored-by: Asim Hussain <[email protected]> * Changed baseline preset text * Made software version mandatory * Removed the requirement to report C and R baseline comment Co-authored-by: Asim Hussain <[email protected]> Co-authored-by: Abhishek Gupta <[email protected]> * Market instruments and grid interconnected infrastructure discussion * Typos * Update Software_Carbon_Intensity_Specification.md 1. The software-boundary was not linked correctly. 2. Readability - LCA definition was defined later, moved it to the first reference. * Update Software_Carbon_Intensity_Specification.md 1. Functional Unit was not linked properly * Update Software_Carbon_Intensity_Specification.md Qualifying that the elements in the SCI equation scale by the same functional unit R * adding units to 'M' and reformatting for consistency (#231) * Add files via upload * Update issue templates * adding units - units added for embodied emissions - moved units to the bottom of each section - reformatted for consistency Co-authored-by: Abhishek Gupta <[email protected]> Co-authored-by: Sean Mcilroy <[email protected]> Co-authored-by: Sean Mcilroy <[email protected]> Co-authored-by: Henry-WattTime <[email protected]> * Eshoppen case study initial draft * Rename eshoppen to eshoppen.md * Added definition on how software causes emissions * changed wording to software systems * Update eshoppen.md Included the changes for the Energy and Embodied emissions values for the database server. * Update Software_Carbon_Intensity.md Updated the Software Carbon Intensity Standard to include guidance on taking into account data center energy efficiency in the Software Boundary section * Update Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md Space added Co-authored-by: Abhishek Gupta <[email protected]> * Added context for SCI reduction for software roles Added context for SCI reduction for software roles * Procedure Flow Updates 1. 'scale' should be first step in the process, as it's the key measure of success 2. 'what' is a bit misleading, and is best defined as a boundary -> 'bound' is a good verb 3. 'how' is a step that best follows the boundary step -> 'bound' is a verb * Reverse list order WG approved * Text edits to introduction * Focus on elimination/abatement (#290) * Changed wording to highlight elimination * Change exclusions WG Approved * Add space WG approved * Restore dev action sentence WG Approved Co-authored-by: Henry-WattTime <[email protected]> * Composable SCI Scores * Update Software_Carbon_Intensity_Specification.md Updated as per WG feedback * add space WG Approved * Spelling correction in the introduction section * Be explicit regarding only eliminations We've made it explicit in `I` but I believe we also need to make it explicit in `M`. * Copywriter updates * Update Software_Carbon_Intensity_Specification.md * Update README.md a few minor improvements to wording on the readme, including a typo or two... * Update README.md WG Approved. Co-authored-by: Abhishek Gupta <[email protected]> * Apply suggestions from code review WG Approved Co-authored-by: Abhishek Gupta <[email protected]> * Update Software_Carbon_Intensity_Specification.md Some suggested changes to the 'scope' section, based on my first impressions/first read... * Update Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md WG approved * Update Software_Carbon_Intensity_Specification.md (#298) * Update Software_Carbon_Intensity_Specification.md A few relatively minor suggested updates to the Introduction * Update Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md WG Approved. * Apply suggestions from code review WG Approved Co-authored-by: Abhishek Gupta <[email protected]> Co-authored-by: Henry-WattTime <[email protected]> Co-authored-by: Abhishek Gupta <[email protected]> * Update Software_Carbon_Intensity_Specification.md (#299) small change to the 'Software Sustainability Actions' section. I'd like to suggest we also rename 'Energy Efficiency' to 'Software Efficiency', but we should discuss that one and I can explain my thinking... Co-authored-by: Henry-WattTime <[email protected]> * Update Software_Carbon_Intensity_Specification.md (#300) minor suggested tweaks to the Procedure section, that might improve readability Co-authored-by: Henry-WattTime <[email protected]> * Re-order formula for clarity (#304) * Re-order formula for clarity Reversed hierarchy from complex formula at the top and simple formula at the bottom. Now you build knowledge as you go down: SCI = C / R -> SCI = (O + M)/R -> SCI = (O formula + M formula)/R. * Update Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md WG removed change. * Update Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md WG Approved * Update issue templates * Update issue templates * Update issue templates * Refine definitions of O & M * Removed table from the definitions section Removed definitions from the document and added link to the GSF dictionary where definitions for the terms used in the document are / will be stored * Removed abbreviations section Removed the abbreviations section and merged it into the definitions section with a reference to the GSF dictionary for both * Reorder Embodied Emissions Calculation * Change Reporting Requirement in Procedure Instead of requiring reporting (which we have not yet developed requirements for) just indicate that reporting should be done. * Updated version note * ISO submission editorials (#331) * Removed Versions section * Replace RFC2119 key words with ISO notation * Revise Scope * Revised/moved Introduction * Added Terms and definitions section * Revised sw sustainability thru location-based * Revised Embodied Emissions & Functional unit * Revised s/w boundary thru comparing an SCI * Revised Code Characteristics thru end; added Bibliography * Apply minor tweaks * Update Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md * Apply suggestions from code review Co-authored-by: Rex Jaeschke <[email protected]> Co-authored-by: Abhishek Gupta <[email protected]> Co-authored-by: Abhishek Gupta <[email protected]> Co-authored-by: Abhishek Gupta <[email protected]> Co-authored-by: Asim Hussain <[email protected]> Co-authored-by: Chris Lloyd-Jones <[email protected]> Co-authored-by: Henry-WattTime <[email protected]> Co-authored-by: Navveen Balani <[email protected]> Co-authored-by: Srinivasan <[email protected]> Co-authored-by: Will Buchanan <[email protected]> Co-authored-by: Sean Mcilroy <[email protected]> Co-authored-by: GadhuNTTDATA <[email protected]> Co-authored-by: Ben Logan <[email protected]> Co-authored-by: Rex Jaeschke <[email protected]>
Green-Software-Foundation · Nov 1, 2022 · 9fbd0c1 · 9fbd0c1
1 parent 74fa470
commit 9fbd0c1
Show file tree

Hide file tree

Showing 8 changed files with 622 additions and 188 deletions.
diff --git a/.github/ISSUE_TEMPLATE/consistency-review.md b/.github/ISSUE_TEMPLATE/consistency-review.md
@@ -0,0 +1,16 @@
+---
+name: Consistency Review
+about: This is a template to used to submit comments during a Consistency Review
+title: "[Consistency Review submission]"
+labels: consistency review
+assignees: atg-abhishek, Henry-WattTime
+
+---
+
+# Consistency Review Submission
+
+## Comment
+
+{outline your observations and suggested changes}
+
+{Add text to the issue title before submitting}
diff --git a/.github/ISSUE_TEMPLATE/faq-submission.md b/.github/ISSUE_TEMPLATE/faq-submission.md
@@ -0,0 +1,16 @@
+---
+name: FAQ submission
+about: FAQ Submissions for SCI
+title: ''
+labels: FAQ
+assignees: atg-abhishek, Henry-WattTime
+
+---
+
+FAQ
+
+  - **Question/Observation**
+        {Text to outline of problem}
+
+  - **Suggested Answer**
+        {Text for suggested answer}
diff --git a/README.md b/README.md
@@ -1,13 +1,13 @@
 # Software Carbon Intensity (SCI) Specification [v.alpha]
 
-A specification that describes how to calculate a carbon intensity for software applications. 
+A specification that describes how to calculate a carbon intensity score for software applications. 
 
 Created and managed by the [Standards Working Group](https://github.com/Green-Software-Foundation/standards_wg) in the [greensoftware.foundation](https://greensoftware.foundation).
 
 ## Project Scope
 This document, the Software Carbon Intensity technical specification, describes how to calculate the carbon intensity of a software application. It describes the methodology of calculating the total carbon emissions and the selection criteria to turn the total into a rate that can be used to achieve real-world, physical emissions reductions, also known as abatement.
 
-Electricity has a carbon intensity depending on where and when it is consumed. An intensity is a rate. It has a numerator and a denominator. A rate provides you with helpful information when considering the growth of a software product. This specification describes the carbon intensity of a software application or service.
+Electricity has a carbon intensity depending on where and when it is consumed. An intensity is a rate. It has a numerator and a denominator. A rate provides you with helpful information when considering how to design, develop, and deploy software applications. This specification describes the carbon intensity of a software application or service.
 
 ## Getting Started
 - The development version of the specification is [here](https://github.com/Green-Software-Foundation/software_carbon_intensity/blob/dev/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md).
@@ -19,10 +19,10 @@ Electricity has a carbon intensity depending on where and when it is consumed. A
 - [Getting started with GitHub](https://green-software-foundation.github.io/github-training/)
 
 ## Contributing
-The recommended approach for getting invlved with the specification is to:
+The recommended approach for getting involved with the specification is to:
 - Read the [development version](https://github.com/Green-Software-Foundation/software_carbon_intensity/blob/dev/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md) of the specification.
-- Raise an issue, question, recommendation in the issues tab above and start a discussion with other members.
-- Once a form of agreement has been reached, then raise a pull request to update the specification with your recommended changes.
+- Raise an issue, question, or recommendation in the issues tab above and start a discussion with other members.
+- Once agreement has been reached, then raise a pull request to update the specification with your recommended changes.
 - Let others know about your pull request by either commenting on the relevant issue or posting in the Standards Working Group slack channel.
 - Pull requests are reviewed and merged during Standards Working Group meetings.
 - Only chairs of the Standards Working Group can merge pull requests.

diff --git a/Software_Carbon_Intensity/Appendix_A.md b/Software_Carbon_Intensity/Appendix_A.md
diff --git a/...re_Carbon_Intensity/Appendix_A_Further_Information_on_Reporting_Requirements.md b/...re_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'
+
+```