From 14cad2226939539b1735dcd6835b96211c29e824 Mon Sep 17 00:00:00 2001 From: Chris Lloyd-Jones <19361656+Sealjay@users.noreply.github.com> Date: Tue, 19 Oct 2021 23:21:47 -0400 Subject: [PATCH 01/17] Add first pass of text --- ...Software_Carbon_Intensity_Specification.md | 76 +++++++++++++------ 1 file changed, 51 insertions(+), 25 deletions(-) diff --git a/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md b/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md index 952b722..b2dadf7 100644 --- a/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md +++ b/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md @@ -71,7 +71,7 @@ The purpose of this specification will be to enable standardization across indus #### Applications Of This Specification -The specification can be applied to any software to measure and reduce its carbon emissions by creating a standardized and practical methodology. +The specification can be applied to any software to measure and reduce its carbon emissions by creating a standardized and practical methodology. #### Target Audience @@ -85,11 +85,11 @@ All actions that can reduce the carbon emissions of a piece of software fall int - **Hardware Efficiency**: Actions taken to make software use less physical resources to perform the same function. - **Carbon Awareness**: Actions taken to time or region-shift software computation to take advantage of clean, renewable or low carbon sources of electricity. -Carbon aware software will optimize the timing and location of operation to minimize emissions associated with operation. This could consist of moving computation to regions with cleaner grid emissions or delaying jobs to cleaner periods (or a combination of both). Energy efficient software will also run on hardware that requires less energy to operate or the software can be re-architected to require less energy to execute. All combined, these effects are reflected in the total operational emissions. +Carbon aware software will optimize the timing and location of operation to minimize emissions associated with operation. This could consist of moving computation to regions with cleaner grid emissions or delaying jobs to cleaner periods (or a combination of both). Energy efficient software will also run on hardware that requires less energy to operate or the software can be re-architected to require less energy to execute. All combined, these effects are reflected in the total operational emissions. ## Software Boundary -The calculation of software carbon intensity MUST include all supporting infrastructure and systems that significantly contributes to the software operation. +The calculation of software carbon intensity MUST include all supporting infrastructure and systems that significantly contributes to the software operation. Supporting infrastructure and systems MAY include: - compute resources @@ -108,9 +108,9 @@ Supporting infrastructure and systems MAY include: - resources to support redundancy - resources to support failover -The entity calculating software carbon intensity MUST report what is included within this boundary. +The entity calculating software carbon intensity MUST report what is included within this boundary. -## Methodology Summary +## Methodology Summary This standard can be used to calculate the real-world emissions associated with software by measuring the total change in global emissions associated with a particular piece of software. @@ -132,7 +132,7 @@ To calculate the carbon intensity the following information is needed: `C = O + M ` = Total amount of carbon the software is emitting over a time period -`R` = Baseline as a denominator (e.g. carbon per additional user, API-call, ML job, etc) +`R` = Baseline as a denominator (e.g. carbon per additional user, API-call, ML job, etc) **carbon intensity (`CI`) compares this carbon against a baseline :** @@ -140,12 +140,12 @@ To calculate the carbon intensity the following information is needed: **carbon delta (`D`) is the difference between two carbon intensities :** -`D = CI(initial) - CI(modified)` = Carbon difference between an initial and modified carbon intensity, and is an optional parameter to quantify gains from implementation of Green Software Engineering methods. +`D = CI(initial) - CI(modified)` = Carbon difference between an initial and modified carbon intensity, and is an optional parameter to quantify gains from implementation of Green Software Engineering methods. ### Lab-based alternatives to Real-world measurements The goal is to calculate how much `C` is emitted per **one unit** of `R`. This is the carbon intensity of your software with respect to `R`. -First, you decide on your baseline unit, your choice of `R`. Then you calculate how much `C` is emitted per unit of `R`. +First, you decide on your baseline unit, your choice of `R`. Then you calculate how much `C` is emitted per unit of `R`. You MAY achieve this by measuring the total real-world carbon emissions of your component `C` over a time period and dividing by the number of `R` units in the same time period to get `C` per `R`. For instance, you may measure data regarding the real-world usage of your application "in the wild" and then divide by the number of users serviced in the same time period to get `C` per `User`. @@ -153,27 +153,27 @@ Or, you MAY model what one unit of `R` looks like and measure the total `C` for You MAY need to use a mixture of both for some components in your application using real-world measurements and for others using a lab-based model of `R`. However, you MUST use a consistent choice of `R` across all your components. -### 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. Because this standard uses a consequential approach, marginal emissions rates should be used for electricity consumption. The marginal emissions rate reflects the change in emissions associcated 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. Because this standard uses a consequential approach, marginal emissions rates should be used for electricity consumption. The marginal emissions rate reflects the change in emissions associcated with a change in demand. -#### Energy Measurement (`E`) -This is a measurement of the energy consumed by a given piece of software for a given task. This must be a measurement of energy consumption in kilowatt hours (kWh) of all supporting infrastructure and systems. This could be applied to several taxonomies: +#### Energy Measurement (`E`) +This is a measurement of the energy consumed by a given piece of software for a given task. This must be a measurement of energy consumption in kilowatt hours (kWh) of all supporting infrastructure and systems. This could be applied to several taxonomies: - Datacenter - Individual machine (e.g. VM/Node) - Individual service (e.g. API call, ML training job) -- Execution of code +- Execution of code #### Location-Based Marginal Carbon Intensity Measurement (`I`) The carbon intensity of electricity is a measure of how much carbon (CO2eq) emissions are produced per kilowatt-hour (kWh) of electricity consumed, for a standard unit of gCO2eq/kWh. This requires 'Marginal' carbon (defined above), and This is the emissions intensity of the marginal power plant which will be turned up if you schedule some compute (e.g. increase electricity demand from the grid) at that moment. -Location-based measures the grid carbon intensity (annual average) of a regional balancing authority. From a developer perspective, only the location-based info is important for having an impact on reducing carbon emissions. This excludes market-based measures, and is distinct from 100% renewable energy claims. +Location-based measures the grid carbon intensity (annual average) of a regional balancing authority. From a developer perspective, only the location-based info is important for having an impact on reducing carbon emissions. This excludes market-based measures, and is distinct from 100% renewable energy claims. The only figure that matters if you’re trying to optimize the scheduling of your compute in real-time is the marginal emissions intensity. This is the emissions intensity of the marginal power plant which will be turned up if you schedule some compute (e.g. increase electricity demand from the grid) at that moment. -### 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 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. -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. @@ -223,7 +223,7 @@ As the SCI specification matures and develops, these core characteristics MUST r ### The SCI takes a systems-footprint 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 @@ -243,20 +243,46 @@ In calculating the SCI value, you SHOULD use the highest granularity data availa - You SHOULD use a value for `R` from the specified [preset list](#preset-list-for-baselines) to compute `CI` but if you choose to use another value for `R`, you MUST provide a reason for that choice. -## Boundaries +## Boundaries [placeholder] ## Exclusions -Because this standard lays out a consequential methodology for calculating the emissions associated with a piece of software, the following must not be included in the calculation: +Because this standard lays out a consequential methodology for calculating the emissions associated with a piece of software, the following must not be included in the calculation: -### Market-based Measures -**“Market-based measures"** are achieved through renewables matching (e.g. PPA for solar near a datacenter) that helps lower the grid carbon intensity for everyone in the area. From a carbon accounting perspective PPAs, RECs etc can allow datacenters to get to “100% renewable”, even if the grid is not 100% renewable 24x7 from a grid perspective. Market-based measures includes, but is not limited to the following: -- Carbon offsets -- Electricity Attribute Certificates (EACs) +### Market-based Measures +**“Market-based measures"** are achieved through renewables matching (e.g. PPA for solar near a datacenter) that helps lower the grid carbon intensity for everyone in the area. From a carbon accounting perspective PPAs, RECs etc can allow datacenters to get to “100% renewable”, even if the grid is not 100% renewable 24x7 from a grid perspective. Market-based measures includes, but is not limited to the following: +- Carbon offsets +- Electricity Attribute Certificates (EACs) - Power Purchase Agreements (PPAs) - Renewable Energy Credits (RECs) -### Infrastructure Measures +### Infrastructure Measures **“Infrastructure measures”** including any infrastructure that integrate renewables via a "direct wire connection" (e.g. a datacenter with solar panels on the roof and a battery storage located onsite). This is conceptually closer to a Microgrid, where there is a higher % of renewable energy usage than the local grid carbon intensity. + +## Reporting Requirements +For an entity to be compliant with this specification, and implementing carbon transparency, certain reporting requirements MUST be met. + +### Data elements to be reported +The following list contains the REQUIRED and OPTIONAL data eleemnts to be reported. Some data elements are defined elsewhere in the specification as REQUIRED, and are included again for completeness. + +- Supporting infrastructure and systems contained within the [Software Boundary](#software-boundary) +- The [Software Carbom Intensity](#reporting-the-sci-value) of the entity itself: + - `CI` MUST be reported + - `C` SHOULD be reported, but where it is not reported, a reason MUST be provided + - The `R` baseline used MUST be reported + - If the `R` baseline used wa not selected from the [pre-set list](#preset-list-for-baselines) for baselines, then a reason for that choice MUST be provided +- Metadata for the SCI value being reported + - Product name MUST be reported + - Contact details, including a name and email, for a point of contact responsible for the report MUST be provided + - Organization SHOULD be provided, where the report is not by an individual contributor + - GUID, + + + + +### Format for reporting \ No newline at end of file From f77e01b5a0d9ec750918626c4e5b5797677db1f3 Mon Sep 17 00:00:00 2001 From: Chris Lloyd-Jones <19361656+Sealjay@users.noreply.github.com> Date: Tue, 19 Oct 2021 23:23:57 -0400 Subject: [PATCH 02/17] Add reference to RFC4122 --- .../Software_Carbon_Intensity_Specification.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md b/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md index b2dadf7..52ff99e 100644 --- a/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md +++ b/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md @@ -16,6 +16,9 @@ This document, the Software Carbon Intensity technical specification, describes [RFC5234] "Augmented BNF for Syntax Specifications: ABNF", D. Crocker, Ed., P. Overell, January 2008, URL: https://tools.ietf.org/rfc/rfc5234.txt + [RFC4122] + "A Universally Unique IDentifier (UUID) URN Namespace", Leach, Mealling, et al, July 2005, URL: https://www.ietf.org/rfc/rfc4122.txt + From 5a97ab8db4e696254f9ba4cc273f8ad57ceb00ea Mon Sep 17 00:00:00 2001 From: Chris Lloyd-Jones <19361656+Sealjay@users.noreply.github.com> Date: Wed, 20 Oct 2021 00:04:59 -0400 Subject: [PATCH 03/17] Added description of valid requirements --- Software_Carbon_Intensity/Appendix_A.md | 1 - ...pendix_A_Reporting_Requirement_Examples.md | 14 +++++ ...Software_Carbon_Intensity_Specification.md | 61 ++++++++++++++++--- 3 files changed, 67 insertions(+), 9 deletions(-) delete mode 100644 Software_Carbon_Intensity/Appendix_A.md create mode 100644 Software_Carbon_Intensity/Appendix_A_Reporting_Requirement_Examples.md diff --git a/Software_Carbon_Intensity/Appendix_A.md b/Software_Carbon_Intensity/Appendix_A.md deleted file mode 100644 index 85f499c..0000000 --- a/Software_Carbon_Intensity/Appendix_A.md +++ /dev/null @@ -1 +0,0 @@ -Add information here diff --git a/Software_Carbon_Intensity/Appendix_A_Reporting_Requirement_Examples.md b/Software_Carbon_Intensity/Appendix_A_Reporting_Requirement_Examples.md new file mode 100644 index 0000000..7cb1f81 --- /dev/null +++ b/Software_Carbon_Intensity/Appendix_A_Reporting_Requirement_Examples.md @@ -0,0 +1,14 @@ +# Appendix A: Reporting Requirement Examples +This appendix provides information of valid machine readable reporting files. + +## YAML Examples + +### 1. Where C is missing + +### 2. Where a pre-provided baseline was not selected + +## Json Examples + +### 1. Where C is missing + +### 2. Where a pre-provided baseline was not selected \ No newline at end of file diff --git a/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md b/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md index 52ff99e..4a38a83 100644 --- a/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md +++ b/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md @@ -19,6 +19,9 @@ This document, the Software Carbon Intensity technical specification, describes [RFC4122] "A Universally Unique IDentifier (UUID) URN Namespace", Leach, Mealling, et al, July 2005, URL: https://www.ietf.org/rfc/rfc4122.txt + [RFC3339] + "Date and Time on the Internet: Timestamps", G. Klyne, et al, July 2002, URL: https://www.ietf.org/rfc/rfc3339.txt + @@ -270,22 +273,64 @@ For an entity to be compliant with this specification, and implementing carbon t ### Data elements to be reported The following list contains the REQUIRED and OPTIONAL data eleemnts to be reported. Some data elements are defined elsewhere in the specification as REQUIRED, and are included again for completeness. +| Name | Identifier | Optionality | Format | Notes | +| - | - | - | - | - | +| Supporting infrastructure and systems contained within the [Software Boundary](#software-boundary) | sci/software-boundary | MUST | List | An array of names, or an array of key-value pairs. +| [Software Carbon Intensity](#reporting-the-sci-value) - `CI`| sci/ci | MUST | Numeric | The [Software Carbon Intensity](#reporting-the-sci-value) of the entity itself. +| [Software Carbon Intensity](#reporting-the-sci-value) - `C`| sci/c | SHOULD | Numeric | Where `C` is not reported, a reason MUST be provided | +| [Software Carbon Intensity](#reporting-the-sci-value) - `C` comment where not provided | sci/c-missing-comment | SHALL | Text | This item SHALL be provided, only where the `sci/c` element is missing. It should describe the reason why `c` is missing. | +| [Software Carbon Intensity](#reporting-the-sci-value) - `R` baseline value| sci/r | MUST | Numeric | +| [Software Carbon Intensity](#reporting-the-sci-value) - `R` baseline source| sci/r-source | MUST | Text | The text should refer to one of the identifiers in the [pre-set list](#preset-list-for-baselines). If it does not, then a freetext comment SHALL be added in `sci/r-source-comment`. | +| [Software Carbon Intensity](#reporting-the-sci-value) - reason for not selecting `R` baseline from provided items| sci/r-source-comment | SHALL | Text | This item SHALL be provided, only where the `sci/r-source` element does not contain one of the identifiers in the [pre-set list](#preset-list-for-baselines). | +| 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/name | SHOULD | Text | This SHALL be populated where the report is not by an individual contributor, otherwise it is not required. | +| GUID | metadata/name | MUST | Guid | Following a format in [RFC4122], provided to uniquely identify this particular product, resource, or service. | +| Version | metadata/name | MAY | Text | | +| Date of Calculation| metadata/name | MUST | Date | Following a format described in [RFC3339] | +| 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 SHALL be a URL to an external document or software repository. | + + + + +### Data format for reporting +The format of your report MUST be machine readable, and SHOULD be in a commonly used format. Examples of commonly used formats include YAML and JSON. + +Examples of valid machine-readable submissions can be found in Appendix A. + +You MAY link to a human readable representation of your report in the further information field, for example, in HTML or PDF format, to provide additional context to your report, or the calculation behind your report. + +This human-readable representation SHALL live outside the GSF, and MAY be referenced in the metadata for your report. + +### Submitting a report +Reports can be made to the `GSF` using a [Pull Request](https://guides.github.com/introduction/flow/). + +Only one machine readable submission MUST exist per unique GUID. Each GUID MUST reference and relate to only one product name. - +When a new SCI report is made, to replace an existing report for a unique product or entity, the pull request MUST update or replace the same file. +Each report must be placed into a unique folder, named after the GUID associated with the product or entity. -### Format for reporting \ No newline at end of file +[Pull Requests](https://guides.github.com/introduction/flow/) should point at this repository: +``` NOTE - ADD GH REPO URL HERE ``` \ No newline at end of file From c8708a4f6424864c6f353b0af79a9e8f41a1f230 Mon Sep 17 00:00:00 2001 From: Chris Lloyd-Jones <19361656+Sealjay@users.noreply.github.com> Date: Wed, 20 Oct 2021 00:11:55 -0400 Subject: [PATCH 04/17] Added first examples --- ...pendix_A_Reporting_Requirement_Examples.md | 59 +++++++++++++++++-- ...Software_Carbon_Intensity_Specification.md | 10 ++-- 2 files changed, 60 insertions(+), 9 deletions(-) diff --git a/Software_Carbon_Intensity/Appendix_A_Reporting_Requirement_Examples.md b/Software_Carbon_Intensity/Appendix_A_Reporting_Requirement_Examples.md index 7cb1f81..36ae1d0 100644 --- a/Software_Carbon_Intensity/Appendix_A_Reporting_Requirement_Examples.md +++ b/Software_Carbon_Intensity/Appendix_A_Reporting_Requirement_Examples.md @@ -3,12 +3,63 @@ This appendix provides information of valid machine readable reporting files. ## YAML Examples -### 1. Where C is missing +### 1. Generic Example where baseline was selected +File name: `25c78b6d-b049-424d-87c1-28f07e41bb23/report.yaml` -### 2. Where a pre-provided baseline was not selected +```yaml +sci: + software-boundary: + - software-package-name + ci: 0.5 + c: 5 + r: 1 + r-source: machine-learning-baseline +metadata: + name: Example Report + contact-name: Responsible Point of Contact + contact-email: report-example@greensoftware.foundation + organization: GSF + guid: 25c78b6d-b049-424d-87c1-28f07e41bb23 + version: '0.1' + calculation-date: '2021-10-20' + calculation-information: 'https://github.com/Green-Software-Foundation/software_carbon_intensity' + +``` +### 2. Where C is missing +File name: `25c78b6d-b049-424d-87c1-28f07e41bb23/report.yaml` + +### 3. Where a pre-provided baseline was not selected +File name: `25c78b6d-b049-424d-87c1-28f07e41bb23/report.yaml` ## Json Examples +### 1. Generic Example where baseline was selected + +File name: `25c78b6d-b049-424d-87c1-28f07e41bb23/report.json` + +```json +{ + "sci": { + "software-boundary":["software-package-name"], + "ci":0.5, + "c":5, + "r":1, + "r-source":"machine-learning-baseline" + }, + "metadata": { + "name":"Example Report", + "contact-name":"Responsible Point of Contact", + "contact-email":"report-example@greensoftware.foundation", + "organization":"GSF", + "guid":"25c78b6d-b049-424d-87c1-28f07e41bb23", + "version":"0.1", + "calculation-date":"2021-10-20", + "calculation-information":"https://github.com/Green-Software-Foundation/software_carbon_intensity" + } +} +``` -### 1. Where C is missing +### 2. Where C is missing +File name: `25c78b6d-b049-424d-87c1-28f07e41bb23/report.json` -### 2. Where a pre-provided baseline was not selected \ No newline at end of file +### 3. Where a pre-provided baseline was not selected +File name: `25c78b6d-b049-424d-87c1-28f07e41bb23/report.json` \ No newline at end of file diff --git a/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md b/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md index 4a38a83..2e2b050 100644 --- a/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md +++ b/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md @@ -271,7 +271,7 @@ Because this standard lays out a consequential methodology for calculating the e For an entity to be compliant with this specification, and implementing carbon transparency, certain reporting requirements MUST be met. ### Data elements to be reported -The following list contains the REQUIRED and OPTIONAL data eleemnts to be reported. Some data elements are defined elsewhere in the specification as REQUIRED, and are included again for completeness. +The following list contains the REQUIRED and OPTIONAL data elements to be reported. Some data elements are defined elsewhere in the specification as REQUIRED, and are included again for completeness. | Name | Identifier | Optionality | Format | Notes | | - | - | - | - | - | @@ -285,10 +285,10 @@ The following list contains the REQUIRED and OPTIONAL data eleemnts to be report | 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/name | SHOULD | Text | This SHALL be populated where the report is not by an individual contributor, otherwise it is not required. | -| GUID | metadata/name | MUST | Guid | Following a format in [RFC4122], provided to uniquely identify this particular product, resource, or service. | -| Version | metadata/name | MAY | Text | | -| Date of Calculation| metadata/name | MUST | Date | Following a format described in [RFC3339] | +| 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. | +| Version | metadata/version | MAY | Text | | +| 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 SHALL be a URL to an external document or software repository. | From ae859ea576e95b00eae709ee837f828520c16825 Mon Sep 17 00:00:00 2001 From: Chris Lloyd-Jones <19361656+Sealjay@users.noreply.github.com> Date: Wed, 20 Oct 2021 00:18:42 -0400 Subject: [PATCH 05/17] Grammar review --- ...pendix_A_Reporting_Requirement_Examples.md | 87 ++++++++++++++++++- ...Software_Carbon_Intensity_Specification.md | 6 +- 2 files changed, 88 insertions(+), 5 deletions(-) diff --git a/Software_Carbon_Intensity/Appendix_A_Reporting_Requirement_Examples.md b/Software_Carbon_Intensity/Appendix_A_Reporting_Requirement_Examples.md index 36ae1d0..301bfbf 100644 --- a/Software_Carbon_Intensity/Appendix_A_Reporting_Requirement_Examples.md +++ b/Software_Carbon_Intensity/Appendix_A_Reporting_Requirement_Examples.md @@ -1,5 +1,5 @@ # Appendix A: Reporting Requirement Examples -This appendix provides information of valid machine readable reporting files. +This appendix provides information of valid machine readable reporting files in JSON, and YAML. Other machine readable file formats are acceptable, so long as they can be parsed in a way that allows for the same identifiers to be extracted. ## YAML Examples @@ -28,9 +28,47 @@ metadata: ### 2. Where C is missing File name: `25c78b6d-b049-424d-87c1-28f07e41bb23/report.yaml` +```yaml +sci: + software-boundary: + - software-package-name + ci: 0.5 + c-missing-comment: A compelling and descriptive reason for why C is missing. + r: 1 + r-source: machine-learning-baseline +metadata: + name: Example Report + contact-name: Responsible Point of Contact + contact-email: report-example@greensoftware.foundation + organization: GSF + guid: 25c78b6d-b049-424d-87c1-28f07e41bb23 + version: '0.1' + calculation-date: '2021-10-20' + calculation-information: 'https://github.com/Green-Software-Foundation/software_carbon_intensity' + +``` ### 3. Where a pre-provided baseline was not selected File name: `25c78b6d-b049-424d-87c1-28f07e41bb23/report.yaml` +```yaml +sci: + software-boundary: + - software-package-name + ci: 0.5 + c: 5 + r: 1 + r-source: another-source + r-source-comment: 'A baseline was not selected, for the purpose of example.' +metadata: + name: Example Report + contact-name: Responsible Point of Contact + contact-email: report-example@greensoftware.foundation + organization: GSF + guid: 25c78b6d-b049-424d-87c1-28f07e41bb23 + version: '0.1' + calculation-date: '2021-10-20' + calculation-information: 'https://github.com/Green-Software-Foundation/software_carbon_intensity' +``` ## Json Examples ### 1. Generic Example where baseline was selected @@ -61,5 +99,50 @@ File name: `25c78b6d-b049-424d-87c1-28f07e41bb23/report.json` ### 2. Where C is missing File name: `25c78b6d-b049-424d-87c1-28f07e41bb23/report.json` +```json +{ + "sci": { + "software-boundary":["software-package-name"], + "ci":0.5, + "c-missing-comment":"A compelling and descriptive reason for why C is missing.", + "r":1, + "r-source":"machine-learning-baseline" + }, + "metadata": { + "name":"Example Report", + "contact-name":"Responsible Point of Contact", + "contact-email":"report-example@greensoftware.foundation", + "organization":"GSF", + "guid":"25c78b6d-b049-424d-87c1-28f07e41bb23", + "version":"0.1", + "calculation-date":"2021-10-20", + "calculation-information":"https://github.com/Green-Software-Foundation/software_carbon_intensity" + } +} +``` + ### 3. Where a pre-provided baseline was not selected -File name: `25c78b6d-b049-424d-87c1-28f07e41bb23/report.json` \ No newline at end of file +File name: `25c78b6d-b049-424d-87c1-28f07e41bb23/report.json` + +```json +{ + "sci": { + "software-boundary":["software-package-name"], + "ci":0.5, + "c":5, + "r":1, + "r-source":"another-source", + "r-source-comment":"A baseline was not selected, for the purpose of example." + }, + "metadata": { + "name":"Example Report", + "contact-name":"Responsible Point of Contact", + "contact-email":"report-example@greensoftware.foundation", + "organization":"GSF", + "guid":"25c78b6d-b049-424d-87c1-28f07e41bb23", + "version":"0.1", + "calculation-date":"2021-10-20", + "calculation-information":"https://github.com/Green-Software-Foundation/software_carbon_intensity" + } +} +``` \ No newline at end of file diff --git a/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md b/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md index 2e2b050..44bdd7b 100644 --- a/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md +++ b/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md @@ -268,7 +268,7 @@ Because this standard lays out a consequential methodology for calculating the e **“Infrastructure measures”** including any infrastructure that integrate renewables via a "direct wire connection" (e.g. a datacenter with solar panels on the roof and a battery storage located onsite). This is conceptually closer to a Microgrid, where there is a higher % of renewable energy usage than the local grid carbon intensity. ## Reporting Requirements -For an entity to be compliant with this specification, and implementing carbon transparency, certain reporting requirements MUST be met. +To comply with this specification and implement carbon transparency, an entity MUST meet these reporting requirements. ### Data elements to be reported The following list contains the REQUIRED and OPTIONAL data elements to be reported. Some data elements are defined elsewhere in the specification as REQUIRED, and are included again for completeness. @@ -315,7 +315,7 @@ The following list contains the REQUIRED and OPTIONAL data elements to be report --> ### Data format for reporting -The format of your report MUST be machine readable, and SHOULD be in a commonly used format. Examples of commonly used formats include YAML and JSON. +The format of your report MUST be machine-readable, and SHOULD be in a commonly used format. Examples of commonly used formats include YAML and JSON. Other formats can be selected, but they MUST allow for the same identifiers to be parsed. Examples of valid machine-readable submissions can be found in Appendix A. @@ -326,7 +326,7 @@ This human-readable representation SHALL live outside the GSF, and MAY be refere ### Submitting a report Reports can be made to the `GSF` using a [Pull Request](https://guides.github.com/introduction/flow/). -Only one machine readable submission MUST exist per unique GUID. Each GUID MUST reference and relate to only one product name. +Only one machine-readable submission MUST exist per unique GUID. Each GUID MUST reference and relate to only one product name. When a new SCI report is made, to replace an existing report for a unique product or entity, the pull request MUST update or replace the same file. From 2bd16ab71843f667d64c250d9fad1c615eaa6416 Mon Sep 17 00:00:00 2001 From: Chris Lloyd-Jones <19361656+Sealjay@users.noreply.github.com> Date: Wed, 20 Oct 2021 09:29:17 -0400 Subject: [PATCH 06/17] Remove JSON --- ...pendix_A_Reporting_Requirement_Examples.md | 81 +------------------ 1 file changed, 2 insertions(+), 79 deletions(-) diff --git a/Software_Carbon_Intensity/Appendix_A_Reporting_Requirement_Examples.md b/Software_Carbon_Intensity/Appendix_A_Reporting_Requirement_Examples.md index 301bfbf..644bb02 100644 --- a/Software_Carbon_Intensity/Appendix_A_Reporting_Requirement_Examples.md +++ b/Software_Carbon_Intensity/Appendix_A_Reporting_Requirement_Examples.md @@ -1,7 +1,7 @@ # Appendix A: Reporting Requirement Examples -This appendix provides information of valid machine readable reporting files in JSON, and YAML. Other machine readable file formats are acceptable, so long as they can be parsed in a way that allows for the same identifiers to be extracted. +This appendix provides an example of validly formed SCI reporting files, which are machine readable. Identifiers should match, to allow for the processing of SCI submissions. -## YAML Examples +## YAML File Examples ### 1. Generic Example where baseline was selected File name: `25c78b6d-b049-424d-87c1-28f07e41bb23/report.yaml` @@ -68,81 +68,4 @@ metadata: calculation-date: '2021-10-20' calculation-information: 'https://github.com/Green-Software-Foundation/software_carbon_intensity' -``` -## Json Examples -### 1. Generic Example where baseline was selected - -File name: `25c78b6d-b049-424d-87c1-28f07e41bb23/report.json` - -```json -{ - "sci": { - "software-boundary":["software-package-name"], - "ci":0.5, - "c":5, - "r":1, - "r-source":"machine-learning-baseline" - }, - "metadata": { - "name":"Example Report", - "contact-name":"Responsible Point of Contact", - "contact-email":"report-example@greensoftware.foundation", - "organization":"GSF", - "guid":"25c78b6d-b049-424d-87c1-28f07e41bb23", - "version":"0.1", - "calculation-date":"2021-10-20", - "calculation-information":"https://github.com/Green-Software-Foundation/software_carbon_intensity" - } -} -``` - -### 2. Where C is missing -File name: `25c78b6d-b049-424d-87c1-28f07e41bb23/report.json` - -```json -{ - "sci": { - "software-boundary":["software-package-name"], - "ci":0.5, - "c-missing-comment":"A compelling and descriptive reason for why C is missing.", - "r":1, - "r-source":"machine-learning-baseline" - }, - "metadata": { - "name":"Example Report", - "contact-name":"Responsible Point of Contact", - "contact-email":"report-example@greensoftware.foundation", - "organization":"GSF", - "guid":"25c78b6d-b049-424d-87c1-28f07e41bb23", - "version":"0.1", - "calculation-date":"2021-10-20", - "calculation-information":"https://github.com/Green-Software-Foundation/software_carbon_intensity" - } -} -``` - -### 3. Where a pre-provided baseline was not selected -File name: `25c78b6d-b049-424d-87c1-28f07e41bb23/report.json` - -```json -{ - "sci": { - "software-boundary":["software-package-name"], - "ci":0.5, - "c":5, - "r":1, - "r-source":"another-source", - "r-source-comment":"A baseline was not selected, for the purpose of example." - }, - "metadata": { - "name":"Example Report", - "contact-name":"Responsible Point of Contact", - "contact-email":"report-example@greensoftware.foundation", - "organization":"GSF", - "guid":"25c78b6d-b049-424d-87c1-28f07e41bb23", - "version":"0.1", - "calculation-date":"2021-10-20", - "calculation-information":"https://github.com/Green-Software-Foundation/software_carbon_intensity" - } -} ``` \ No newline at end of file From 721172647d7dae44c207d4ebccd6246d76b26a65 Mon Sep 17 00:00:00 2001 From: Chris Lloyd-Jones <19361656+Sealjay@users.noreply.github.com> Date: Wed, 20 Oct 2021 10:19:59 -0400 Subject: [PATCH 07/17] Move table structure to appendix --- ...r_Information_on_Reporting_Requirements.md | 101 ++++++++++++++++++ ...pendix_A_Reporting_Requirement_Examples.md | 71 ------------ 2 files changed, 101 insertions(+), 71 deletions(-) create mode 100644 Software_Carbon_Intensity/Appendix_A_Further_Information_on_Reporting_Requirements.md delete mode 100644 Software_Carbon_Intensity/Appendix_A_Reporting_Requirement_Examples.md diff --git a/Software_Carbon_Intensity/Appendix_A_Further_Information_on_Reporting_Requirements.md b/Software_Carbon_Intensity/Appendix_A_Further_Information_on_Reporting_Requirements.md new file mode 100644 index 0000000..9226148 --- /dev/null +++ b/Software_Carbon_Intensity/Appendix_A_Further_Information_on_Reporting_Requirements.md @@ -0,0 +1,101 @@ +# 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-boundary) | sci/software-boundary | MUST | List | An array of names, or an array of key-value pairs. +| [Software Carbon Intensity](#reporting-the-sci-value) - `CI`| sci/ci | MUST | Numeric | The [Software Carbon Intensity](#reporting-the-sci-value) of the entity itself. +| [Software Carbon Intensity](#reporting-the-sci-value) - `C`| sci/c | SHOULD | Numeric | Where `C` is not reported, a reason MUST be provided | +| [Software Carbon Intensity](#reporting-the-sci-value) - `C` comment where not provided | sci/c-missing-comment | SHALL | Text | This item SHALL be provided, only where the `sci/c` element is missing. It should describe the reason why `c` is missing. | +| [Software Carbon Intensity](#reporting-the-sci-value) - `R` baseline value| sci/r | MUST | Numeric | +| [Software Carbon Intensity](#reporting-the-sci-value) - `R` baseline source| sci/r-source | MUST | Text | The text should refer to one of the identifiers in the [pre-set list](#preset-list-for-baselines). If it does not, then a freetext comment SHALL be added in `sci/r-source-comment`. | +| [Software Carbon Intensity](#reporting-the-sci-value) - reason for not selecting `R` baseline from provided items| sci/r-source-comment | SHALL | Text | This item SHALL be provided, only where the `sci/r-source` element does not contain one of the identifiers in the [pre-set list](#preset-list-for-baselines). | +| 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 | MAY | 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 SHALL be a URL to an external document or software repository. | + +## YAML File Examples + +### 1. Generic Example where baseline was selected +File name: `25c78b6d-b049-424d-87c1-28f07e41bb23/report.yaml` + +```yaml +sci: + software-boundary: + - software-package-name + ci: 0.5 + c: 5 + r: 1 + r-source: machine-learning-baseline +metadata: + name: Example Report + contact-name: Responsible Point of Contact + contact-email: report-example@greensoftware.foundation + 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. Where C is missing +File name: `25c78b6d-b049-424d-87c1-28f07e41bb23/report.yaml` + +```yaml +sci: + software-boundary: + - software-package-name + ci: 0.5 + c-missing-comment: A compelling and descriptive reason for why C is missing. + r: 1 + r-source: machine-learning-baseline +metadata: + name: Example Report + contact-name: Responsible Point of Contact + contact-email: report-example@greensoftware.foundation + 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' + +``` +### 3. Where a pre-provided baseline was not selected +File name: `25c78b6d-b049-424d-87c1-28f07e41bb23/report.yaml` +```yaml +sci: + software-boundary: + - software-package-name + ci: 0.5 + c: 5 + r: 1 + r-source: another-source + r-source-comment: 'A baseline was not selected, for the purpose of example.' +metadata: + name: Example Report + contact-name: Responsible Point of Contact + contact-email: report-example@greensoftware.foundation + 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' + +``` \ No newline at end of file diff --git a/Software_Carbon_Intensity/Appendix_A_Reporting_Requirement_Examples.md b/Software_Carbon_Intensity/Appendix_A_Reporting_Requirement_Examples.md deleted file mode 100644 index 644bb02..0000000 --- a/Software_Carbon_Intensity/Appendix_A_Reporting_Requirement_Examples.md +++ /dev/null @@ -1,71 +0,0 @@ -# Appendix A: Reporting Requirement Examples -This appendix provides an example of validly formed SCI reporting files, which are machine readable. Identifiers should match, to allow for the processing of SCI submissions. - -## YAML File Examples - -### 1. Generic Example where baseline was selected -File name: `25c78b6d-b049-424d-87c1-28f07e41bb23/report.yaml` - -```yaml -sci: - software-boundary: - - software-package-name - ci: 0.5 - c: 5 - r: 1 - r-source: machine-learning-baseline -metadata: - name: Example Report - contact-name: Responsible Point of Contact - contact-email: report-example@greensoftware.foundation - organization: GSF - guid: 25c78b6d-b049-424d-87c1-28f07e41bb23 - version: '0.1' - calculation-date: '2021-10-20' - calculation-information: 'https://github.com/Green-Software-Foundation/software_carbon_intensity' - -``` -### 2. Where C is missing -File name: `25c78b6d-b049-424d-87c1-28f07e41bb23/report.yaml` - -```yaml -sci: - software-boundary: - - software-package-name - ci: 0.5 - c-missing-comment: A compelling and descriptive reason for why C is missing. - r: 1 - r-source: machine-learning-baseline -metadata: - name: Example Report - contact-name: Responsible Point of Contact - contact-email: report-example@greensoftware.foundation - organization: GSF - guid: 25c78b6d-b049-424d-87c1-28f07e41bb23 - version: '0.1' - calculation-date: '2021-10-20' - calculation-information: 'https://github.com/Green-Software-Foundation/software_carbon_intensity' - -``` -### 3. Where a pre-provided baseline was not selected -File name: `25c78b6d-b049-424d-87c1-28f07e41bb23/report.yaml` -```yaml -sci: - software-boundary: - - software-package-name - ci: 0.5 - c: 5 - r: 1 - r-source: another-source - r-source-comment: 'A baseline was not selected, for the purpose of example.' -metadata: - name: Example Report - contact-name: Responsible Point of Contact - contact-email: report-example@greensoftware.foundation - organization: GSF - guid: 25c78b6d-b049-424d-87c1-28f07e41bb23 - version: '0.1' - calculation-date: '2021-10-20' - calculation-information: 'https://github.com/Green-Software-Foundation/software_carbon_intensity' - -``` \ No newline at end of file From 4195d4dc418974ec9f594df2afd744fc6d9e35fe Mon Sep 17 00:00:00 2001 From: Chris Lloyd-Jones <19361656+Sealjay@users.noreply.github.com> Date: Wed, 20 Oct 2021 10:20:07 -0400 Subject: [PATCH 08/17] Remove reporting process --- ...Software_Carbon_Intensity_Specification.md | 76 +++++-------------- 1 file changed, 20 insertions(+), 56 deletions(-) diff --git a/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md b/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md index 44bdd7b..8b4dfd9 100644 --- a/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md +++ b/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md @@ -268,69 +268,33 @@ Because this standard lays out a consequential methodology for calculating the e **“Infrastructure measures”** including any infrastructure that integrate renewables via a "direct wire connection" (e.g. a datacenter with solar panels on the roof and a battery storage located onsite). This is conceptually closer to a Microgrid, where there is a higher % of renewable energy usage than the local grid carbon intensity. ## Reporting Requirements -To comply with this specification and implement carbon transparency, an entity MUST meet these reporting requirements. - -### Data elements to be reported -The following list contains the REQUIRED and OPTIONAL data elements to be reported. Some data elements are defined elsewhere in the specification as REQUIRED, and are included again for completeness. - -| Name | Identifier | Optionality | Format | Notes | -| - | - | - | - | - | -| Supporting infrastructure and systems contained within the [Software Boundary](#software-boundary) | sci/software-boundary | MUST | List | An array of names, or an array of key-value pairs. -| [Software Carbon Intensity](#reporting-the-sci-value) - `CI`| sci/ci | MUST | Numeric | The [Software Carbon Intensity](#reporting-the-sci-value) of the entity itself. -| [Software Carbon Intensity](#reporting-the-sci-value) - `C`| sci/c | SHOULD | Numeric | Where `C` is not reported, a reason MUST be provided | -| [Software Carbon Intensity](#reporting-the-sci-value) - `C` comment where not provided | sci/c-missing-comment | SHALL | Text | This item SHALL be provided, only where the `sci/c` element is missing. It should describe the reason why `c` is missing. | -| [Software Carbon Intensity](#reporting-the-sci-value) - `R` baseline value| sci/r | MUST | Numeric | -| [Software Carbon Intensity](#reporting-the-sci-value) - `R` baseline source| sci/r-source | MUST | Text | The text should refer to one of the identifiers in the [pre-set list](#preset-list-for-baselines). If it does not, then a freetext comment SHALL be added in `sci/r-source-comment`. | -| [Software Carbon Intensity](#reporting-the-sci-value) - reason for not selecting `R` baseline from provided items| sci/r-source-comment | SHALL | Text | This item SHALL be provided, only where the `sci/r-source` element does not contain one of the identifiers in the [pre-set list](#preset-list-for-baselines). | -| 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. | -| Version | metadata/version | MAY | Text | | -| 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 SHALL be a URL to an external document or software repository. | - - - - -### Data format for reporting -The format of your report MUST be machine-readable, and SHOULD be in a commonly used format. Examples of commonly used formats include YAML and JSON. Other formats can be selected, but they MUST allow for the same identifiers to be parsed. - -Examples of valid machine-readable submissions can be found in Appendix A. + - The version of the SCI specification which you are reporting against MUST be provided. -You MAY link to a human readable representation of your report in the further information field, for example, in HTML or PDF format, to provide additional context to your report, or the calculation behind your report. - -This human-readable representation SHALL live outside the GSF, and MAY be referenced in the metadata for your report. - -### Submitting a report -Reports can be made to the `GSF` using a [Pull Request](https://guides.github.com/introduction/flow/). - -Only one machine-readable submission MUST exist per unique GUID. Each GUID MUST reference and relate to only one product name. - -When a new SCI report is made, to replace an existing report for a unique product or entity, the pull request MUST update or replace the same file. - -Each report must be placed into a unique folder, named after the GUID associated with the product or entity. - -[Pull Requests](https://guides.github.com/introduction/flow/) should point at this repository: -``` NOTE - ADD GH REPO URL HERE ``` \ No newline at end of file +#### Optional reporting requirements +- The [Software Carbon Intensity](#reporting-the-sci-value) of the entity itself. + - `C` SHOULD be reported, but where it is not reported, a reason MUST be provided +- Metadata for the SCI value being reported + - Organization SHOULD be provided, where the report is not by an individual contributor + - A software version for the software product about which this report is made, MAY be provided. + - More information on your calculation methodology MAY be provided, as a freetext comment. + - More information on your report MAY be provided, as a URL linking to an external document or software repository. From d4666448772a8528e7ee20e0810b2d0729d0c9c7 Mon Sep 17 00:00:00 2001 From: Chris Lloyd-Jones <19361656+Sealjay@users.noreply.github.com> Date: Wed, 20 Oct 2021 10:22:42 -0400 Subject: [PATCH 09/17] Changed software boundary reporting requirements --- ...r_Information_on_Reporting_Requirements.md | 11 ++++------ ...Software_Carbon_Intensity_Specification.md | 20 +++++++++---------- 2 files changed, 14 insertions(+), 17 deletions(-) diff --git a/Software_Carbon_Intensity/Appendix_A_Further_Information_on_Reporting_Requirements.md b/Software_Carbon_Intensity/Appendix_A_Further_Information_on_Reporting_Requirements.md index 9226148..29acda9 100644 --- a/Software_Carbon_Intensity/Appendix_A_Further_Information_on_Reporting_Requirements.md +++ b/Software_Carbon_Intensity/Appendix_A_Further_Information_on_Reporting_Requirements.md @@ -10,7 +10,7 @@ The following list contains the REQUIRED and OPTIONAL data elements to be report | Name | Identifier | Optionality | Format | Notes | | - | - | - | - | - | -| Supporting infrastructure and systems contained within the [Software Boundary](#software-boundary) | sci/software-boundary | MUST | List | An array of names, or an array of key-value pairs. +| Supporting infrastructure and systems contained within the [Software Boundary](#software-boundary) | sci/software-boundary | MUST | Text | A description of the software boundary for the entity. | | [Software Carbon Intensity](#reporting-the-sci-value) - `CI`| sci/ci | MUST | Numeric | The [Software Carbon Intensity](#reporting-the-sci-value) of the entity itself. | [Software Carbon Intensity](#reporting-the-sci-value) - `C`| sci/c | SHOULD | Numeric | Where `C` is not reported, a reason MUST be provided | | [Software Carbon Intensity](#reporting-the-sci-value) - `C` comment where not provided | sci/c-missing-comment | SHALL | Text | This item SHALL be provided, only where the `sci/c` element is missing. It should describe the reason why `c` is missing. | @@ -35,8 +35,7 @@ File name: `25c78b6d-b049-424d-87c1-28f07e41bb23/report.yaml` ```yaml sci: - software-boundary: - - software-package-name + software-boundary: 'The software boundary of this report is limited to a single markdown file, as it is provided for example only.' ci: 0.5 c: 5 r: 1 @@ -58,8 +57,7 @@ File name: `25c78b6d-b049-424d-87c1-28f07e41bb23/report.yaml` ```yaml sci: - software-boundary: - - software-package-name + software-boundary: 'The software boundary of this report is limited to a single markdown file, as it is provided for example only.' ci: 0.5 c-missing-comment: A compelling and descriptive reason for why C is missing. r: 1 @@ -80,8 +78,7 @@ metadata: File name: `25c78b6d-b049-424d-87c1-28f07e41bb23/report.yaml` ```yaml sci: - software-boundary: - - software-package-name + software-boundary: 'The software boundary of this report is limited to a single markdown file, as it is provided for example only.' ci: 0.5 c: 5 r: 1 diff --git a/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md b/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md index 8b4dfd9..741336b 100644 --- a/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md +++ b/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md @@ -278,23 +278,23 @@ This human-readable representation SHALL live outside the GSF, and MAY be refere ### Report structure and required data elements The data elements have mandatory key names, which can be found in Appendix A, along with examples of validly formed YAML reporting files . #### Mandatory reporting elements -- Supporting infrastructure and systems contained within the [Software Boundary](#software-boundary) +- Supporting infrastructure and systems contained within the [Software Boundary](#software-boundary). - The [Software Carbon Intensity](#reporting-the-sci-value) of the entity itself. - - `CI` MUST be reported - - The `R` baseline used MUST be reported - - If the `R` baseline used wa not selected from the [pre-set list](#preset-list-for-baselines) for baselines, then a reason for that choice MUST be provided -- Metadata for the SCI value being reported - - Product name MUST be reported - - Contact details, including a name and email, for a point of contact responsible for the report MUST be provided + - `CI` MUST be reported. + - The `R` baseline used MUST be reported. + - If the `R` baseline used wa not selected from the [pre-set list](#preset-list-for-baselines) for baselines, then a reason for that choice MUST be provided. +- Metadata for the SCI value being reported. + - Product name MUST be reported. + - Contact details, including a name and email, for a point of contact responsible for the report MUST be provided. - A GUID, following a format described in [RFC4122], MUST be provided to uniquely identify this particular product, resource, or service. - The date the calculation was made, following a format described in [RFC3339], MUST be provided. - The version of the SCI specification which you are reporting against MUST be provided. #### Optional reporting requirements - The [Software Carbon Intensity](#reporting-the-sci-value) of the entity itself. - - `C` SHOULD be reported, but where it is not reported, a reason MUST be provided -- Metadata for the SCI value being reported - - Organization SHOULD be provided, where the report is not by an individual contributor + - `C` SHOULD be reported, but where it is not reported, a reason MUST be provided. +- Metadata for the SCI value being reported. + - Organization SHOULD be provided, where the report is not by an individual contributor. - A software version for the software product about which this report is made, MAY be provided. - More information on your calculation methodology MAY be provided, as a freetext comment. - More information on your report MAY be provided, as a URL linking to an external document or software repository. From 89b6920e03ef9dedd54270df5ac0e303f276e52a Mon Sep 17 00:00:00 2001 From: Chris Lloyd-Jones <19361656+Sealjay@users.noreply.github.com> Date: Wed, 20 Oct 2021 10:25:35 -0400 Subject: [PATCH 10/17] Removed other references to reports --- .../Software_Carbon_Intensity_Specification.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md b/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md index 741336b..46281ae 100644 --- a/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md +++ b/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md @@ -114,8 +114,6 @@ Supporting infrastructure and systems MAY include: - resources to support redundancy - resources to support failover -The entity calculating software carbon intensity MUST report what is included within this boundary. - ## Methodology Summary This standard can be used to calculate the real-world emissions associated with software by measuring the total change in global emissions associated with a particular piece of software. @@ -217,6 +215,14 @@ You MAY use simple models to estimate embodied emissions; however, you SHOULD us ### Preset List for Baselines [placeholder] +| Baseline Name / Identifier | Description | Value | +| - | - | - | +| Example | Example | Value | +``` +Added as placeholder, as baselines are required for reporting. +``` + + ## Core Characteristics As the SCI specification matures and develops, these core characteristics MUST remain true. @@ -243,12 +249,6 @@ To achieve impact at scale, the SCI needs to encourage adoption through ease of In calculating the SCI value, you SHOULD use the highest granularity data available to you to compute each of `O`, `E`, `I`, and `M`. In cases where temporal granular data is not available, annual values SHALL be used which are the lowest acceptable level of granularity. -### Reporting the SCI value - -- You MUST report the `CI` value and you SHOULD report the `C` value but if you are unable to report the `C` value, you MUST provide a reason for why you are unable to do so. -- You SHOULD use a value for `R` from the specified [preset list](#preset-list-for-baselines) to compute `CI` but if you choose to use another value for `R`, you MUST provide a reason for that choice. - - ## Boundaries [placeholder] From d3ea485ee67677f16cab7f3a1afebc23b3e9e185 Mon Sep 17 00:00:00 2001 From: Chris Lloyd-Jones <19361656+Sealjay@users.noreply.github.com> Date: Thu, 21 Oct 2021 10:31:16 -0400 Subject: [PATCH 11/17] updated URLs --- ...urther_Information_on_Reporting_Requirements.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/Software_Carbon_Intensity/Appendix_A_Further_Information_on_Reporting_Requirements.md b/Software_Carbon_Intensity/Appendix_A_Further_Information_on_Reporting_Requirements.md index 29acda9..b2380a5 100644 --- a/Software_Carbon_Intensity/Appendix_A_Further_Information_on_Reporting_Requirements.md +++ b/Software_Carbon_Intensity/Appendix_A_Further_Information_on_Reporting_Requirements.md @@ -10,13 +10,13 @@ The following list contains the REQUIRED and OPTIONAL data elements to be report | Name | Identifier | Optionality | Format | Notes | | - | - | - | - | - | -| Supporting infrastructure and systems contained within the [Software Boundary](#software-boundary) | sci/software-boundary | MUST | Text | A description of the software boundary for the entity. | -| [Software Carbon Intensity](#reporting-the-sci-value) - `CI`| sci/ci | MUST | Numeric | The [Software Carbon Intensity](#reporting-the-sci-value) of the entity itself. -| [Software Carbon Intensity](#reporting-the-sci-value) - `C`| sci/c | SHOULD | Numeric | Where `C` is not reported, a reason MUST be provided | -| [Software Carbon Intensity](#reporting-the-sci-value) - `C` comment where not provided | sci/c-missing-comment | SHALL | Text | This item SHALL be provided, only where the `sci/c` element is missing. It should describe the reason why `c` is missing. | -| [Software Carbon Intensity](#reporting-the-sci-value) - `R` baseline value| sci/r | MUST | Numeric | -| [Software Carbon Intensity](#reporting-the-sci-value) - `R` baseline source| sci/r-source | MUST | Text | The text should refer to one of the identifiers in the [pre-set list](#preset-list-for-baselines). If it does not, then a freetext comment SHALL be added in `sci/r-source-comment`. | -| [Software Carbon Intensity](#reporting-the-sci-value) - reason for not selecting `R` baseline from provided items| sci/r-source-comment | SHALL | Text | This item SHALL be provided, only where the `sci/r-source` element does not contain one of the identifiers in the [pre-set list](#preset-list-for-baselines). | +| 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) - `CI`| sci/ci | 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) - `C`| sci/c | SHOULD | Numeric | Where `C` is not reported, a reason MUST be provided | +| [Software Carbon Intensity](Software_Carbon_Intensity_Specification#reporting-the-sci-value) - `C` comment where not provided | sci/c-missing-comment | SHALL | Text | This item SHALL be provided, only where the `sci/c` element is missing. It should describe the reason why `c` is missing. | +| [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 should refer to one of the identifiers in the [pre-set list](Software_Carbon_Intensity_Specification#preset-list-for-baselines). If it does not, then a freetext comment SHALL be added in `sci/r-source-comment`. | +| [Software Carbon Intensity](Software_Carbon_Intensity_Specification#reporting-the-sci-value) - reason for not selecting `R` baseline from provided items| sci/r-source-comment | SHALL | Text | This item SHALL be provided, only where the `sci/r-source` element does not contain one of the identifiers in the [pre-set list](Software_Carbon_Intensity_Specification#preset-list-for-baselines). | | 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. | From 0daac68c54a756dba82e101b9a8e1431a12f3802 Mon Sep 17 00:00:00 2001 From: Chris Lloyd-Jones <19361656+Sealjay@users.noreply.github.com> Date: Thu, 21 Oct 2021 15:36:45 +0100 Subject: [PATCH 12/17] Update Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md Co-authored-by: Asim Hussain --- .../Software_Carbon_Intensity_Specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md b/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md index 46281ae..3579523 100644 --- a/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md +++ b/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md @@ -282,7 +282,7 @@ The data elements have mandatory key names, which can be found in Appendix A, al - The [Software Carbon Intensity](#reporting-the-sci-value) of the entity itself. - `CI` MUST be reported. - The `R` baseline used MUST be reported. - - If the `R` baseline used wa not selected from the [pre-set list](#preset-list-for-baselines) for baselines, then a reason for that choice MUST be provided. + - If the `R` baseline used was not selected from the [pre-set list](#preset-list-for-baselines) for baselines, then a reason for that choice MUST be provided. - Metadata for the SCI value being reported. - Product name MUST be reported. - Contact details, including a name and email, for a point of contact responsible for the report MUST be provided. From b75d076dd474e9774f8c4b752a7f41b3cf3643d1 Mon Sep 17 00:00:00 2001 From: Chris Lloyd-Jones <19361656+Sealjay@users.noreply.github.com> Date: Thu, 21 Oct 2021 15:36:54 +0100 Subject: [PATCH 13/17] Update Software_Carbon_Intensity/Appendix_A_Further_Information_on_Reporting_Requirements.md Co-authored-by: Asim Hussain --- .../Appendix_A_Further_Information_on_Reporting_Requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Software_Carbon_Intensity/Appendix_A_Further_Information_on_Reporting_Requirements.md b/Software_Carbon_Intensity/Appendix_A_Further_Information_on_Reporting_Requirements.md index 29acda9..f871e77 100644 --- a/Software_Carbon_Intensity/Appendix_A_Further_Information_on_Reporting_Requirements.md +++ b/Software_Carbon_Intensity/Appendix_A_Further_Information_on_Reporting_Requirements.md @@ -26,7 +26,7 @@ The following list contains the REQUIRED and OPTIONAL data elements to be report | 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 SHALL be 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 Examples From ef8199e01b29c5a4d962e14b85c602dae3624107 Mon Sep 17 00:00:00 2001 From: Chris Lloyd-Jones <19361656+Sealjay@users.noreply.github.com> Date: Thu, 21 Oct 2021 15:39:04 +0100 Subject: [PATCH 14/17] Update Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md Co-authored-by: Asim Hussain --- .../Software_Carbon_Intensity_Specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md b/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md index 3579523..cc94311 100644 --- a/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md +++ b/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md @@ -280,7 +280,7 @@ The data elements have mandatory key names, which can be found in Appendix A, al #### Mandatory reporting elements - Supporting infrastructure and systems contained within the [Software Boundary](#software-boundary). - The [Software Carbon Intensity](#reporting-the-sci-value) of the entity itself. - - `CI` MUST be reported. + - `SCI` MUST be reported. - The `R` baseline used MUST be reported. - If the `R` baseline used was not selected from the [pre-set list](#preset-list-for-baselines) for baselines, then a reason for that choice MUST be provided. - Metadata for the SCI value being reported. From e0c5518d9a84c540cb60b7aad43d5d2910702ab6 Mon Sep 17 00:00:00 2001 From: Chris Lloyd-Jones <19361656+Sealjay@users.noreply.github.com> Date: Thu, 21 Oct 2021 10:39:28 -0400 Subject: [PATCH 15/17] Changed baseline preset text --- .../Software_Carbon_Intensity_Specification.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md b/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md index 46281ae..3763dd4 100644 --- a/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md +++ b/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md @@ -215,14 +215,6 @@ You MAY use simple models to estimate embodied emissions; however, you SHOULD us ### Preset List for Baselines [placeholder] -| Baseline Name / Identifier | Description | Value | -| - | - | - | -| Example | Example | Value | -``` -Added as placeholder, as baselines are required for reporting. -``` - - ## Core Characteristics As the SCI specification matures and develops, these core characteristics MUST remain true. From 6d98b15b24ca074bd670f4dee443bf8349a183d7 Mon Sep 17 00:00:00 2001 From: Chris Lloyd-Jones <19361656+Sealjay@users.noreply.github.com> Date: Thu, 21 Oct 2021 10:45:00 -0400 Subject: [PATCH 16/17] Made software version mandatory --- ...ppendix_A_Further_Information_on_Reporting_Requirements.md | 4 ++-- .../Software_Carbon_Intensity_Specification.md | 3 +-- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/Software_Carbon_Intensity/Appendix_A_Further_Information_on_Reporting_Requirements.md b/Software_Carbon_Intensity/Appendix_A_Further_Information_on_Reporting_Requirements.md index 82538c7..c53ce61 100644 --- a/Software_Carbon_Intensity/Appendix_A_Further_Information_on_Reporting_Requirements.md +++ b/Software_Carbon_Intensity/Appendix_A_Further_Information_on_Reporting_Requirements.md @@ -11,7 +11,7 @@ The following list contains the REQUIRED and OPTIONAL data elements to be report | 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) - `CI`| sci/ci | 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) - `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) - `C`| sci/c | SHOULD | Numeric | Where `C` is not reported, a reason MUST be provided | | [Software Carbon Intensity](Software_Carbon_Intensity_Specification#reporting-the-sci-value) - `C` comment where not provided | sci/c-missing-comment | SHALL | Text | This item SHALL be provided, only where the `sci/c` element is missing. It should describe the reason why `c` is missing. | | [Software Carbon Intensity](Software_Carbon_Intensity_Specification#reporting-the-sci-value) - `R` baseline value| sci/r | MUST | Numeric | @@ -22,7 +22,7 @@ The following list contains the REQUIRED and OPTIONAL data elements to be 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 | MAY | Text | | +| 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. | diff --git a/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md b/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md index b4c9f0c..0138074 100644 --- a/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md +++ b/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md @@ -281,12 +281,11 @@ The data elements have mandatory key names, which can be found in Appendix A, al - A GUID, following a format described in [RFC4122], MUST be provided to uniquely identify this particular product, resource, or service. - The date the calculation was made, following a format described in [RFC3339], MUST be provided. - The version of the SCI specification which you are reporting against MUST be provided. - + - A software version for the software product about which this report is made, MUST be provided. #### Optional reporting requirements - The [Software Carbon Intensity](#reporting-the-sci-value) of the entity itself. - `C` SHOULD be reported, but where it is not reported, a reason MUST be provided. - Metadata for the SCI value being reported. - Organization SHOULD be provided, where the report is not by an individual contributor. - - A software version for the software product about which this report is made, MAY be provided. - More information on your calculation methodology MAY be provided, as a freetext comment. - More information on your report MAY be provided, as a URL linking to an external document or software repository. From 25c2ecd98553087582bf6108b8e82b49797041db Mon Sep 17 00:00:00 2001 From: Chris Lloyd-Jones <19361656+Sealjay@users.noreply.github.com> Date: Thu, 21 Oct 2021 10:59:22 -0400 Subject: [PATCH 17/17] Removed the requirement to report C and R baseline comment --- ...r_Information_on_Reporting_Requirements.md | 33 ++++++++----------- ...Software_Carbon_Intensity_Specification.md | 10 +++--- 2 files changed, 18 insertions(+), 25 deletions(-) diff --git a/Software_Carbon_Intensity/Appendix_A_Further_Information_on_Reporting_Requirements.md b/Software_Carbon_Intensity/Appendix_A_Further_Information_on_Reporting_Requirements.md index c53ce61..20788da 100644 --- a/Software_Carbon_Intensity/Appendix_A_Further_Information_on_Reporting_Requirements.md +++ b/Software_Carbon_Intensity/Appendix_A_Further_Information_on_Reporting_Requirements.md @@ -12,11 +12,8 @@ The following list contains the REQUIRED and OPTIONAL data elements to be report | - | - | - | - | - | | 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) - `C`| sci/c | SHOULD | Numeric | Where `C` is not reported, a reason MUST be provided | -| [Software Carbon Intensity](Software_Carbon_Intensity_Specification#reporting-the-sci-value) - `C` comment where not provided | sci/c-missing-comment | SHALL | Text | This item SHALL be provided, only where the `sci/c` element is missing. It should describe the reason why `c` is missing. | -| [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 should refer to one of the identifiers in the [pre-set list](Software_Carbon_Intensity_Specification#preset-list-for-baselines). If it does not, then a freetext comment SHALL be added in `sci/r-source-comment`. | -| [Software Carbon Intensity](Software_Carbon_Intensity_Specification#reporting-the-sci-value) - reason for not selecting `R` baseline from provided items| sci/r-source-comment | SHALL | Text | This item SHALL be provided, only where the `sci/r-source` element does not contain one of the identifiers in the [pre-set list](Software_Carbon_Intensity_Specification#preset-list-for-baselines). | +| [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. | @@ -28,16 +25,15 @@ The following list contains the REQUIRED and OPTIONAL data elements to be report | 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 Examples +## YAML File Example -### 1. Generic Example where baseline was selected +### 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.' - ci: 0.5 - c: 5 + sci: 0.5 r: 1 r-source: machine-learning-baseline metadata: @@ -52,14 +48,13 @@ metadata: calculation-information: 'https://github.com/Green-Software-Foundation/software_carbon_intensity' ``` -### 2. Where C is missing +### 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.' - ci: 0.5 - c-missing-comment: A compelling and descriptive reason for why C is missing. + sci: 0.5 r: 1 r-source: machine-learning-baseline metadata: @@ -72,23 +67,23 @@ metadata: 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. Where a pre-provided baseline was not selected + +### 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.' - ci: 0.5 - c: 5 + sci: 0.5 r: 1 - r-source: another-source - r-source-comment: 'A baseline was not selected, for the purpose of example.' + r-source: machine-learning-baseline metadata: name: Example Report - contact-name: Responsible Point of Contact + contact-name: Individual Point of Contact contact-email: report-example@greensoftware.foundation - organization: GSF guid: 25c78b6d-b049-424d-87c1-28f07e41bb23 entity-version: '0.1' sci-version: 1.0 diff --git a/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md b/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md index 0138074..0026fc6 100644 --- a/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md +++ b/Software_Carbon_Intensity/Software_Carbon_Intensity_Specification.md @@ -268,13 +268,13 @@ You MAY link to a human readable representation of your report in the further in This human-readable representation SHALL live outside the GSF, and MAY be referenced in the metadata for your report. ### Report structure and required data elements -The data elements have mandatory key names, which can be found in Appendix A, along with examples of validly formed YAML reporting files . +The data elements have mandatory key names, [which can be found in Appendix A, along with examples of validly formed YAML reporting files](Appendix_A_Further_Information_on_Reporting_Requirements.md). #### Mandatory reporting elements - Supporting infrastructure and systems contained within the [Software Boundary](#software-boundary). - The [Software Carbon Intensity](#reporting-the-sci-value) of the entity itself. - `SCI` MUST be reported. - - The `R` baseline used MUST be reported. - - If the `R` baseline used was not selected from the [pre-set list](#preset-list-for-baselines) for baselines, then a reason for that choice MUST be provided. + - `R` value MUST be reported. + - The `R` baseline used MUST be reported - either from the [pre-set list](#preset-list-for-baselines) for baselines, or a similar baseline. - Metadata for the SCI value being reported. - Product name MUST be reported. - Contact details, including a name and email, for a point of contact responsible for the report MUST be provided. @@ -283,9 +283,7 @@ The data elements have mandatory key names, which can be found in Appendix A, al - The version of the SCI specification which you are reporting against MUST be provided. - A software version for the software product about which this report is made, MUST be provided. #### Optional reporting requirements -- The [Software Carbon Intensity](#reporting-the-sci-value) of the entity itself. - - `C` SHOULD be reported, but where it is not reported, a reason MUST be provided. - Metadata for the SCI value being reported. - Organization SHOULD be provided, where the report is not by an individual contributor. - More information on your calculation methodology MAY be provided, as a freetext comment. - - More information on your report MAY be provided, as a URL linking to an external document or software repository. + - More information on your report MAY be provided, and this MUST be a URL to an external document or software repository.