@grnsft/if 0.3.1 → 0.3.2

package/github-processes.md

@@ -0,0 +1,158 @@
+
+## IF Repositories
+
+- [`if`](https://github.com/Green-Software-Foundation/if)
+    - source code for the IF
+- [`if-plugins`](https://github.com/Green-Software-Foundation/if-plugins)
+    - source code for standard library of plugins
+    - IF core team commit to maintaining these plugins 
+- [`if-unofficial-plugins`](https://github.com/Green-Software-Foundation/if-unofficial-plugins)
+    - source code for plugins relying on third-party data/APIs
+    - intended to be deprecated and removed in mid-term future
+    - plugins in this repo should be handed over to relevant organizations to maintain
+- [`if-plugin-template`](https://github.com/Green-Software-Foundation/if-plugin-template)
+    - template for new plugins
+    - intended for builders to bootstrap IF-compatible plugin development
+- [`if-standards`](https://github.com/Green-Software-Foundation/if-standards)
+    - not currently used, but intended to be the home of params.ts
+    - will have a dedicated discussion board and governance to set IF standards
+- [`if-exhaust plugins`](https://github.com/Green-Software-Foundation/if-exhaust-plugins)
+    - not currently used
+    - intended to become a separate repo just for exhaust plugins
+    - requires strict rules from if
+
+
+## Branch names and purposes
+
+Our main repositories all have two branches: `main` and `release`.
+Here are the rules applied to each branch:
+
+### `if`, `if-plugins`, `if-unofficial-plugins` and `if-exhaust-plugins`
+
+#### `main`
+- target branch for PRs
+- PRs can be merged into `main` with two core team reviews, one being QA
+- `main` regularly advances ahead of the `release` branch
+- merged into `release` periodically, only after full QA approval
+- pushing directly to `main` is forbidden - all changes are by PR
+- PRs will not be merged if they do not pass CI/CD
+
+#### `release`
+
+- release is our stable branch
+- it is protected and only merged into when we have a fully QA-approved `main` state that we want to release
+- npm packages are released using `release` branch
+- PRs into `release` are forbidden except to update tests, README, Github config, CI/CD or release config.
+- Pushing directly to `release` is forbidden
+- `release` should always satisfy a basic set of regression and scenario tests
+- merging `main` into `release` requires that all automated tests pass and two core team members have approved, one being QA.
+
+### `if-plugin-template` 
+
+- we only maintain a single branch: `main`
+- PRs to `main` can be merged after one approval from core team
+- Pushing directly to `main` is possible but discouraged
+
+
+### `if-docs`
+
+- we only maintain a single branch - `main`
+- PRs to `main` can be merged after one approval from core team
+- Pushing directly to `main` is possible but discouraged
+
+### When can we break our rules?
+
+- `release` branches have the strictest rules. We should never override the process outlined above for `release` branches in any repository.
+- On `main` we can be slightly more flexible. It is acceptable to skip QA for PRs that only change typos, documentation or comments. Any changes to source code or tests should be QA approved before merge.
+- In emergency scenarios where an urgent hotfix is required it might be required to skip QA review on `main` branches - this should only happen with QA authorization so QA can retroactively test as soon as possible.
+
+## DCO
+
+We require contributors to conform to the DCO agreement on our repositories. This means either signing commits or explicitly adding a DCO commit message. This ensures all contributors agree to the conditions imposed by our licenses and adhere to our expected practices. The DCO must be satisfied in order to PRs to be merged.
+
+## Commits
+
+Commits are expected to conform to the [conventional-commits](https://www.conventionalcommits.org/en/v1.0.0/) syntax.
+Commits are expected to be signed and have descriptive commit messages.
+We might ask people to provide new messages in some circumstances or to break their PRs into smaller logical units.
+
+## PR triage
+
+We run a weekly PR triage call on Thursdays. The most important outcome of this call is to examine open PRs and issues across all the IF repositories and determine which ones include changes that we might want to merge. This initial sift for changes that are or are not aligned with our goals for the IF should be prioritized above technical comments and fixes.
+
+Some reasons why a PR might not pass triage:
+
+- changes are not aligned with our vision for IF
+- we do not see a strong reason for making a change
+- changes are obviously technically incorrect
+- changes are too large to properly review (e.g. covering too many files)
+- too many changes are made in too few commits
+- commit messages are ambiguous
+- PR description is too short, vague or imprecise
+- PR would for some other reason take too long for core team to assess
+- PR makes changes that do not conform to our license
+- PR makes use of a third-party API or dataset in an illegitimate way (e.g. exposing data that should be paywalled)
+
+After a PR has passed triage, it can be assigned to a core team member to review. Developer review precedes QA review. Community PRs (PRs raised from outside the core team) will *always* go through a full QA vetting procedure before being merged.
+
+We intend to respond to new PRs and issues within 3 days of the ticket being opened, even if only with a brief message thanking the OP and explaining the triage process.
+
+
+## Labels
+
+```
+//review status labels 
+awaiting-triage 
+triage-pass 
+awaiting-review 
+review-pass 
+awaiting-qa 
+qa-pass 
+changes-needed 
+
+//change type labels 
+fix 
+feature 
+docs 
+package 
+other 
+
+// size labels 
+small 
+medium 
+large 
+
+// priority labels 
+high-priority 
+med-priority 
+low-priority 
+
+//delay explanation labels 
+abandoned 
+blocked 
+backlogged
+
+// other labels
+project-management
+agenda
+discussion
+help-wanted
+good-first-issue
+```
+
+Each PR is expected to have one label from each category (except `other`) assigned to it at all times.
+
+
+## Releases
+
+We aim to release fortnightly, every other Tuesday. We release npm packages for `if`, `if-plugins`, `if-unofficial-plugins`, and `if-plugin-template`.
+
+## Hotfixes
+
+We will hotfix by raising PRs into `release` when necessary. These PRs require sign-off by a core developer and our QA engineer. 
+
+If more than two hotfixes are required on a particular release, the team will call a spike meeting to determine the causes of the bugs, identify any changes required to our QA process and determine next steps for fixing the release. 
+
+Hotfixes on release can be merged back into `main` when they have been fully QA tested.
+
+We intend for hotfixes to be as infrequent as possible.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@grnsft/if",
   "description": "Impact Framework",
-  "version": "v0.3.1",
+  "version": "v0.3.2",
   "author": {
     "name": "Green Software Foundation",
     "email": "info@gsf.com"

package/src/builtins/README.md

@@ -279,7 +279,6 @@ tree:
               carbon: 200
               energy: 200
               requests: 380
-
 ```
 
 
@@ -673,44 +672,43 @@ graph:
         - teads-curve
       config:
         group-by:
-          - cloud-region
+          - cloud/region
           - instance-type
       inputs:
         - timestamp: 2023-07-06T00:00
-          duration: 300 
-          instance-type: A1 
-          region: uk-west
+          duration: 300
+          instance-type: A1
+          cloud/region: uk-west
           cpu-util: 99
-        - timestamp: 2023-07-06T05:00 
-          duration: 300 
-          instance-type: A1 
-          region: uk-west
-          cpu-util: 23	  
+        - timestamp: 2023-07-06T05:00
+          duration: 300
+          instance-type: A1
+          cloud/region: uk-west
+          cpu-util: 23
         - timestamp: 2023-07-06T10:00
           duration: 300
-          instance-type: A1 
-          region: uk-west
+          instance-type: A1
+          cloud/region: uk-west
           cpu-util: 12
         - timestamp: 2023-07-06T00:00 # note this time restarts at the start timstamp
           duration: 300 
           instance-type: B1
-          region: uk-west
+          cloud/region: uk-west
           cpu-util: 11
-        - timestamp: 2023-07-06T05:00 
-          duration: 300 
+        - timestamp: 2023-07-06T05:00
+          duration: 300
           instance-type: B1
-          region: uk-west
+          cloud/region: uk-west
           cpu-util: 67
         - timestamp: 2023-07-06T10:00
           duration: 300 
           instance-type: B1
-          region: uk-west
-          cpu-util: 1	  
+          cloud/region: uk-west
+          cpu-util: 1
 ```
 
 However, each observation contains an `instance-type` field that varies between observations. There are two instance types being represented in this array of observations. This means there are duplicate entries for the same timestamp in this array. This is the problem that `group-by` solves. You provide `instance-type` as a key to the `group-by` plugin and it extracts the data belonging to the different instances and separates them into independent arrays. The above example would be restructured so that instance types `A1` and `B1` have their own data, as follows:
 
-
 ```yaml
 graph:
   children:
@@ -721,7 +719,7 @@ graph:
       config:
         group-by:
           groups:
-            - cloud-region
+            - cloud/region
             - instance-type
       children:
         A1:
@@ -729,35 +727,35 @@ graph:
             - timestamp: 2023-07-06T00:00
                 duration: 300
                 instance-type: A1
-                region: uk-west
+                cloud/region: uk-west
                 cpu-util: 99
             - timestamp: 2023-07-06T05:00
                 duration: 300
                 instance-type: A1
-                region: uk-west
+                cloud/region: uk-west
                 cpu-util: 23
             - timestamp: 2023-07-06T10:00
                 duration: 300
                 instance-type: A1
-                region: uk-west
+                cloud/region: uk-west
                 cpu-util: 12
         B1:
             inputs:
             - timestamp: 2023-07-06T00:00
                 duration: 300
                 instance-type: B1
-                region: uk-east
+                cloud/region: uk-east
                 cpu-util: 11
             - timestamp: 2023-07-06T05:00
                 duration: 300
                 instance-type: B1
-                region: uk-east
+                cloud/region: uk-east
                 cpu-util: 67
             - timestamp: 2023-07-06T10:00
                 duration: 300
                 instance-type: B1
-                region: uk-east
-                cpu-util: 1          
+                cloud/region: uk-east
+                cpu-util: 1
 ```
 
 ### Using `group-by`
@@ -769,9 +767,9 @@ The initialization looks as follows:
 ```yaml
 initialize:
 plugins:
-group-by: 
-    path: 'builtin'
-    method: GroupBy
+group-by:
+  path: 'builtin'
+  method: GroupBy
 ```
 
 You then have to provide config defining which keys to group by in each component. This is done at the component level (i.e. not global config).
@@ -782,19 +780,18 @@ For example:
 tree:
   children:
     my-app:
-      pipeline:     
+      pipeline:
         - group-by
       config:
         group-by:
           group:
-            - region
+            - cloud/region
             - instance-type
 ```
 
-In the example above, the plugin would regroup the input data for the specific component by `region` and by `instance-type`.
-
-Assuming the values `A1` and `B1` are found for `instance-type` and the values `uk-east` and `uk-west` are found for `region`, the result of `group-by` would look similar to the following:
+In the example above, the plugin would regroup the input data for the specific component by `cloud/region` and by `instance-type`.
 
+Assuming the values `A1` and `B1` are found for `instance-type` and the values `uk-east` and `uk-west` are found for `cloud/region`, the result of `group-by` would look similar to the following:
 
 ```yaml
 tree:
@@ -805,7 +802,7 @@ tree:
       config:
         group-by:
           groups:
-            - region
+            - cloud/region
             - instance-type
       children:
         uk-west:
@@ -815,17 +812,17 @@ tree:
                 - timestamp: 2023-07-06T00:00
                   duration: 300
                   instance-type: A1
-                  region: uk-west
+                  cloud/region: uk-west
                   cpu-util: 99
                 - timestamp: 2023-07-06T05:00
                   duration: 300
                   instance-type: A1
-                  region: uk-west
+                  cloud/region: uk-west
                   cpu-util: 23
                 - timestamp: 2023-07-06T10:00
                   duration: 300
                   instance-type: A1
-                  region: uk-west
+                  cloud/region: uk-west
                   cpu-util: 12
         uk-east:
           children:
@@ -834,19 +831,18 @@ tree:
                 - timestamp: 2023-07-06T00:00
                   duration: 300
                   instance-type: B1
-                  region: uk-east
+                  cloud/region: uk-east
                   cpu-util: 11
                 - timestamp: 2023-07-06T05:00
                   duration: 300
                   instance-type: B1
-                  region: uk-east
+                  cloud/region: uk-east
                   cpu-util: 67
                 - timestamp: 2023-07-06T10:00
                   duration: 300
                   instance-type: B1
-                  region: uk-east
-                  cpu-util: 1     
+                  cloud/region: uk-east
+                  cpu-util: 1
 ```
 
 This reorganized data can then be used to feed the rest of a computation pipeline.
-

package/examples/manifests/cim.yml

@@ -1,20 +0,0 @@
-name: cloud-instance-metadata
-description: example impl invoking Cloud Instance Metadata plugin
-tags:
-initialize:
-  plugins:
-    cloud-metadata:
-      method: CloudMetadata
-      path: "@grnsft/if-plugins"
-tree:
-  children:
-    child:
-      pipeline:
-        - cloud-metadata
-      config:
-      inputs:
-        - timestamp: 2023-07-06T00:00 # [KEYWORD] [NO-SUBFIELDS] time when measurement occurred
-          cloud/vendor: aws
-          cloud/instance-type: m5n.large
-          duration: 100
-          cpu/utilization: 10

package/examples/manifests/teads-aws.yml

@@ -1,22 +0,0 @@
-name: teads-aws
-description: simple demo invoking TeadsAWS model
-tags:
-initialize:
-  plugins:
-    teads-aws:
-      method: TeadsAWS
-      path: "@grnsft/if-unofficial-plugins"
-      global-config:
-        interpolation: linear
-tree:
-  children:
-    child:
-      pipeline:
-        - teads-aws # duration & config -> embodied
-      defaults:
-        cloud/instance-type: m5n.large
-        cpu/expected-lifespan: 252288000
-      inputs:
-        - timestamp: 2023-07-06T00:00
-          duration: 3600
-          cpu/utilization: 10