Skip to content

Commit

Permalink
Merge pull request #868 from Green-Software-Foundation/release-v0.5.0…
Browse files Browse the repository at this point in the history 
…-beta.0

Release v0.5.0-beta.0
  • Loading branch information
@narekhovhannisyan
narekhovhannisyan authored Jun 28, 2024
2 parents 1342df8 + 2479a27 commit ffe9d09
Show file tree
Hide file tree
Showing 176 changed files with 4,553 additions and 1,714 deletions.
9 changes: 4 additions & 5 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,15 +24,15 @@ The following document is a rule set of guidelines for contributing.

## What and when to contribute

You can contribute anything to the IF, but we are likely to close out unsolicited PRs without merging them. Our issue board is completely open and we have tags (`help-wanted`, `good-first-issue`) to help contributors to choose tasks to work on. We recommend speaking to the core team on Github before starting working on an issue. You can do this by raising an issue or commenting on an existing issue. This helps us to direct your energy in directions that are aligned with our roadmap, prevent multiple people working on the same task, and better manage our board. This all makes it much more likely that your work will get merged.
You can contribute anything to the IF, but we are likely to close out unsolicited PRs without merging them. Our issue board is completely open and we have tags (`core-only`, `good-first-issue`) to help contributors to choose tasks to work on. If an issue is unassigned and does not have the `core-only` label, it is available to work on. We recommend speaking to the core team on Github before starting working on an issue. You can do this by commenting on an existing issue or discussion thread or starting a new one if appropriate. This helps us to direct your energy in directions that are aligned with our roadmap, prevent multiple people working on the same task, and better manage our board. This all makes it much more likely that your work will get merged.

You can also contribute by participating in discussions on our mailing list at [[email protected]](https://groups.google.com/u/1/a/greensoftware.foundation/g/if-community). We send out weekly updates that includes what we've shipped, what we're working on and how you can get involved each week.

## Reporting bugs

We appreciate bug reports! If you experience an issue with IF or one of our plugins, you can report it using our bug reporting template. To do this:
We appreciate bug reports! If you experience an issue with IF, you can report it using our bug reporting template. To do this:

1. Go to the [IF repository](https://github.com/Green-Software-Foundation/if) (or [plugin repository](https://github.com/Green-Software-Foundation/if-plugins) if you bug relates to a specific plugin)
1. Go to the [IF repository](https://github.com/Green-Software-Foundation/if)
2. Click on the `Issues` tab
3. Click on `Create New Issue` and select the `Bug Report` template.
4. Fill out the requested information.
Expand All @@ -46,8 +46,7 @@ The assessment rubric is as follows:
| | Consequence | Severity |
| ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | -------- |
| Bugs in IF core leading to incorrect calculations | unusable framework | 5 |
| Bugs in if-plugins leading to incorrect calculations | core pathways fail, IF very limited in functionality | 5 |
| Bugs in if-unofficial-pluginsd leading to incorrect calculations | Third party plugins harder to use, limits IF to standard lib | 3 |
| Bugs in builtins leading to incorrect calculations | core pathways fail, IF very limited in functionality | 5 |
| Bugs in template | Harder to build plugins, ecosystem growth is impacted | 2 |
| Bugs in docs | product does not match expectation, hard to debug, frustration, loss of adoption | 2 |
| Security flaw: privacy related | leak user data, unlikely to achieve adoption in serious orgs | 5 |
Expand Down
47 changes: 14 additions & 33 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,6 @@
> [!IMPORTANT]
> Incubation Project: This project is an incubation project being run inside the Green Software Foundation; as such, we DON’T recommend using it in any critical use case. Incubation projects are experimental, offer no support guarantee, have minimal governance and process, and may be retired at any moment. This project may one day Graduate, in which case this disclaimer will be removed.
**Note** We have recently (March 2024) refactored the IF codebase and introduced some changes affecting both users and developers. You can read our migration guide [HERE](./Refactor-migration-guide.md) to help you update to the latest version!

[Impact Framework](https://greensoftwarefoundation.atlassian.net/wiki/spaces/~612dd45e45cd76006a84071a/pages/17072136/Opensource+Impact+Engine+Framework) (IF) is an [Incubation](https://oc.greensoftware.foundation/project-lifecycle.html#incubation) project from the [Open Source Working Group](https://greensoftwarefoundation.atlassian.net/wiki/spaces/~612dd45e45cd76006a84071a/pages/852049/Open+Source+Working+Group) in the [Green Software Foundation](https://greensoftware.foundation/).

**Our documentation is online at [if.greensoftware.foundation](https://if.greensoftware.foundation/)**

**IF** is a framework to **M**odel, **M**easure, si**M**ulate and **M**onitor the environmental impacts of software
Expand All @@ -23,74 +19,60 @@ Read the [specification and design docs](https://if.greensoftware.foundation) to

## Get started

The first thing to understand is that IF is a framework for running plugins. This means that in order to do some calculations, you need to load some plugins from some external resource. We provide a [standard library of plugins](https://github.com/Green-Software-Foundation/if-plugins) and a repository of [community plugins](https://github.com/Green-Software-Foundation/if-unofficial-plugins) to get you started.
IF is a framework for running pipelines of plugins that operate on a set of observations. This is all configured using a manifest file. We provide a standard library of plugins that come bundled with IF - we refer to these as `builtins`. We also have an [Explorer](https://explorer.if.greensoftware.foundation) where anyone can list third party plugins you can install.

Start by installing framework itself:
Start by installing the latest version of IF:

```sh
npm install -g "@grnsft/if"
```

Then installing some plugins:

```sh
npm install -g "@grnsft/if-plugins"
```

Then create a `manifest` file that describes your application (see our docs for a detailed explanation).

Then, run `if` using the following command:

```sh
ie --manifest <path-to-your-manifest-file>
if-run --manifest <path-to-your-manifest-file> --stdout
## or you can use aliases
ie -m <path-to-your-manifest-file>
if-run -m <path-to-your-manifest-file> -s

```

Note that above command will not print the final output. In order to print the final output to the console, run `if` using the optional stdout argument:
Note that above command will print your outputs to the console. You can also provide the `--output` command to save your outputs to a yaml file:

```sh
ie --manifest <path-to-your-manifest-file> --stdout
## or using aliases
ie -m <path-to-your-manifest-file> -s
if-run -m <path-to-your-manifest> -o <savepath>
```

You can also add a savepath for your output yaml in order to have the output stored in a file. Note that you also have to add configuration to your manifest to enable this, as follows:
Note that you also have to add configuration to your manifest to enable this, as follows:

```yaml
initialize:
output:
- yaml
```
On the command line:
```sh
ie --manifest <path-to-your-manifest-file> --output <your-savepath>
## or using aliases
ie -m <path-to-your-manifest-file> -o <your-savepath>
```

The `ie` CLI tool will configure and run the plugins defined in your input `yaml` (`manifest`) and return the results as an output `yaml` (`output`).
The `if-run` CLI tool will configure and run the plugins defined in your input `yaml` (`manifest`) and return the results as an output `yaml` (`output`).

Use the `debug` command if you want to diagnose and fix errors in your plugin:

```sh
ie --manifest <path-to-your-manifest-file> --debug
if-run --manifest <path-to-your-manifest-file> --debug
```

Use the `help` command if you need guidance about the available commands

```sh
ie --help
if-run --help
## or using alias
ie -h
if-run -h
```

## Documentation

Please read our documentation at [if.greensoftware.foundation](https://if.greensoftware.foundation/)


## Video walk-through

Watch this video to learn how to create and run a `manifest`.
Expand All @@ -107,11 +89,10 @@ We have a public mailing list at [[email protected]](https:/

To contribute to IF, please fork this repository and raise a pull request from your fork.

You can check our issue board for issues tagged `help-wanted`. These are issues that are not currently, actively being worked on by the core team but are well-scoped enough for someone to pick up. We recommend commenting on the issue to start a chat with the core team, then start working on the issue when you have been assigned to it. This process helps to ensure your work is aligned with our roadmap and makes it much more likely that your changes will get merged compared to unsolicited PRs.
You can check our issue board for issues. We mark some issues `core-only` if they are somehow sensitive and we want one of our core developers to handle it. Any other issues are open for the community to work on. We recommend commenting on the issue to start a chat with the core team, then start working on the issue when you have been assigned to it. This process helps to ensure your work is aligned with our roadmap and makes it much more likely that your changes will get merged compared to unsolicited PRs.

Please read the full contribution guidelines at [if.greensoftware.foundation](https://if.greensoftware.foundation/Contributing)

The same guidelines also apply to `if-docs`, `if-plugins` and `if-unofficial-plugins`.

## Bug reports

Expand Down
11 changes: 5 additions & 6 deletions Refactor-migration-guide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,13 +12,13 @@ There have been some name changes to the CLI, specifically:
The command line tool has been renamed from `impact-engine` to simply `ie`. This means that to invoke the Impact Framework on the command line you simply use

```
ie ...
if-run ...
```
- `impl` --> `manifest`
We have deprecated the original `impl` and `ompl` terminology across all our repositories and on the command line. Now, to pass a manifest file to IF, you use the `--manifest` command, as follows:
```sh
ie --manifest <path-to-manifest>
if-run --manifest <path-to-manifest>
```
Expand All @@ -27,7 +27,7 @@ There have been some name changes to the CLI, specifically:
We have deprecated the original `impl` and `ompl` terminology across all our repositories and on the command line. Now, to define a savepath for your output file, you use the `--output` command, as follows:
```sh
ie --manifest <path-to-manifest> --output <savepath>
if-run --manifest <path-to-manifest> --output <savepath>
```
## Outputs
Expand Down Expand Up @@ -55,13 +55,13 @@ npm i @grnsft/if
Then run IF using the following command:

```sh
ie --manifest <path-to-manifest>
if-run --manifest <path-to-manifest>
```

This will dump the output to the console. If you want to save the output to a yaml file, provide a savepath to the `--output` command:

```sh
ie --manifest <path-to-manifest> --output <savepath>
if-run --manifest <path-to-manifest> --output <savepath>
```


Expand Down Expand Up @@ -186,7 +186,6 @@ There have also been some changes to the structure of manifest files. Some of th
device/expected-lifespan: 94608000 # 3 years in seconds
resources-reserved: 1
resources-total: 8
functional-unit-time: "1 min"
```
Expand Down
2 changes: 1 addition & 1 deletion jest.config.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,8 @@ module.exports = {
},
modulePathIgnorePatterns: [
'./build',
'./src/__tests__/unit/lib/manifest',
'./src/__tests__/integration/helpers',
'./src/__tests__/integration/test-data',
],
coveragePathIgnorePatterns: ['src/config', 'src/types'],
};
96 changes: 73 additions & 23 deletions manifests/bugs/aggregation-error-wrong-metric.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,26 +7,62 @@ aggregation:
type: "both"
initialize:
plugins:
"teads-curve":
path: "@grnsft/if-unofficial-plugins"
method: TeadsCurve
"interpolate":
method: Interpolation
path: 'builtin'
global-config:
interpolation: spline
"sci-e":
path: "@grnsft/if-plugins"
method: SciE
method: linear
x: [0, 10, 50, 100]
y: [0.12, 0.32, 0.75, 1.02]
input-parameter: 'cpu/utilization'
output-parameter: 'cpu-factor'
"cpu-factor-to-wattage":
method: Multiply
path: builtin
global-config:
input-parameters: ["cpu-factor", "cpu/thermal-design-power"]
output-parameter: "cpu-wattage"
"wattage-times-duration":
method: Multiply
path: builtin
global-config:
input-parameters: ["cpu-wattage", "duration"]
output-parameter: "cpu-wattage-times-duration"
"wattage-to-energy-kwh":
method: Divide
path: "builtin"
global-config:
numerator: cpu-wattage-times-duration
denominator: 3600000
output: cpu-energy-raw
"calculate-vcpu-ratio":
method: Divide
path: "builtin"
global-config:
numerator: vcpus-total
denominator: vcpus-allocated
output: vcpu-ratio
"correct-cpu-energy-for-vcpu-ratio":
method: Divide
path: "builtin"
global-config:
numerator: cpu-energy-raw
denominator: vcpu-ratio
output: cpu-energy-kwh
"sci-embodied":
path: "builtin"
method: SciEmbodied
"sci-o":
path: "@grnsft/if-plugins"
method: SciO
"operational-carbon":
method: Multiply
path: builtin
global-config:
input-parameters: ["cpu-energy-kwh", "grid/carbon-intensity"]
output-parameter: "carbon"
"sci":
path: "builtin"
method: Sci
global-config:
functional-unit: "requests"
functional-unit-time: "1 minute"
"time-sync":
method: TimeSync
path: "builtin"
Expand All @@ -42,10 +78,14 @@ tree:
children:
child-1:
pipeline:
- teads-curve
- sci-e
- interpolate
- cpu-factor-to-wattage
- wattage-times-duration
- wattage-to-energy-kwh
- calculate-vcpu-ratio
- correct-cpu-energy-for-vcpu-ratio
- sci-embodied
- sci-o
- operational-carbon
- time-sync
- sci
config:
Expand All @@ -59,36 +99,43 @@ tree:
device/emissions-embodied: 1533.120 # gCO2eq
time-reserved: 3600 # 1hr in seconds
device/expected-lifespan: 94608000 # 3 years in seconds
resources-reserved: 1
resources-total: 8
functional-unit-time: "1 min"
vcpus-allocated: 1
vcpus-total: 8
inputs:
- timestamp: "2023-12-12T00:00:00.000Z"
cloud/instance-type: A1
cloud/region: uk-west
duration: 1
cpu/utilization: 10
requests: 100
- timestamp: "2023-12-12T00:00:01.000Z"
duration: 5
cpu/utilization: 20
cloud/instance-type: A1
cloud/region: uk-west
requests: 100
- timestamp: "2023-12-12T00:00:06.000Z"
duration: 7
cpu/utilization: 15
cloud/instance-type: A1
cloud/region: uk-west
requests: 100
- timestamp: "2023-12-12T00:00:13.000Z"
duration: 30
cloud/instance-type: A1
cloud/region: uk-west
cpu/utilization: 15
requests: 100
child-2:
pipeline:
- teads-curve
- sci-e
- interpolate
- cpu-factor-to-wattage
- wattage-times-duration
- wattage-to-energy-kwh
- calculate-vcpu-ratio
- correct-cpu-energy-for-vcpu-ratio
- sci-embodied
- sci-o
- operational-carbon
- time-sync
- sci
config:
Expand All @@ -102,27 +149,30 @@ tree:
device/emissions-embodied: 1533.120 # gCO2eq
time-reserved: 3600 # 1hr in seconds
device/expected-lifespan: 94608000 # 3 years in seconds
resources-reserved: 1
resources-total: 8
functional-unit-time: "1 min"
vcpus-allocated: 1
vcpus-total: 8
inputs:
- timestamp: "2023-12-12T00:00:00.000Z"
duration: 1
cpu/utilization: 30
cloud/instance-type: A1
cloud/region: uk-west
requests: 100
- timestamp: "2023-12-12T00:00:01.000Z"
duration: 5
cpu/utilization: 28
cloud/instance-type: A1
cloud/region: uk-west
requests: 100
- timestamp: "2023-12-12T00:00:06.000Z"
duration: 7
cpu/utilization: 40
cloud/instance-type: A1
cloud/region: uk-west
requests: 100
- timestamp: "2023-12-12T00:00:13.000Z"
duration: 30
cpu/utilization: 33
cloud/instance-type: A1
cloud/region: uk-west
requests: 100
9 changes: 6 additions & 3 deletions manifests/bugs/azure-importer-ignoring-defaults.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,9 +28,12 @@ initialize:
input-parameter: network/energy
coefficient: 1000
output-parameter: network/energy
"sci-o":
method: SciO
path: "@grnsft/if-plugins"
"operational-carbon":
method: Multiply
path: builtin
global-config:
input-parameters: ["energy", "grid/carbon-intensity"]
output-parameter: "carbon-operational"
"group-by":
path: "builtin"
method: GroupBy
Expand Down
Loading

0 comments on commit ffe9d09

Please sign in to comment.