Add docs for usage of co2js within the impact framework

[alexzurbonsen]

Hey Chris, hey everyone, co2js is also available as a plugin within the impact framework (IF), a recent project by the Green Software Foundation. I have used it in an IF plugin to measure/estimate the carbon emissions of webpage loads. Would you be interested in making the connection to IF more visible, may be add usage hints for IF and the measure webpage plugin etc. to make usage as simple as possible? Best, Alex

[mrchrisadams]

hi @alexzurbonsen - yes, this would be great!

However, I'm not sure what files would need to stay inside the CO2 js repo to make this work, and I'd welcome some pointers from you.

When I look at the sample manifest file in your linked repo, it looks like the manifest file is doing two things:

1. declaring a bunch of plugins, one of which is co2.js

name: measure-webpage-demo
description: example manifest for estimating carbon emissions of a webpage
tags:
initialize:
  outputs:
    - yaml
  plugins:
    "timer-start":
      method: TimerStart
      path: '@wr24-greenit/if-webpage-plugins'
    "timer-stop":
      method: TimerStop
      path: '@wr24-greenit/if-webpage-plugins'
    "green-hosting":
      method: GreenHosting
      path: '@wr24-greenit/if-webpage-plugins'
    "measure-webpage":
      method: MeasureWebpage
      path: '@wr24-greenit/if-webpage-plugins'
    "co2js":
      method: Co2js
      path: '@wr24-greenit/if-webpage-plugins'
      global-config:
        options:
          firstVisitPercentage: 0.9
          returnVisitPercentage: 0.1

2. And using some features of CO2.js in the plugins in a pipeline, once the earlier steps have worked out the total data transfer.

I think the config block is where you have defined various params for calling each plugin in the pipeline. So for co2js, you're passing in the swd model, and this might be where you pass in further params for that pipeline stage.

Is this sort of how it works?

tree:
  children:
    child:
      pipeline:
        - timer-start
        - measure-webpage
        - timer-stop
        - green-hosting
        - co2js
      config:
        co2js:
          type: swd
        measure-webpage:
          lighthouse: true
          scrollToBottom: true
      inputs:
        - timestamp: '2024-01-01T00:00:00Z' # will be replaced by the actual timestamp
          duration: 1 # will be replaced by the time it took to execute the measure-webpage plugin
          url: https://www.tngtech.com
          resets: [true] # tells the timer-stop method to replace timestamp and duration

I'm aware that whole manifest file contains plugins that do quite a lot, like running a full browser and so on - this would likely increase the size of the co2js library, and quite a lot of effort has gone into keeping the library small, as well as the number of dependencies low.

To keep this smalll to start off with, I wonder how much would be needed to extract co2js from the this repo as a first step so instead of needing to pull in a plugin like this:

    "co2js":
      method: Co2js
      path: '@wr24-greenit/if-webpage-plugins'

You might have something like this, where in the pipeline it's acting as as wrapper that called some of the swd model functions by default:

    "co2js":
      method: Co2js
      path: '@TGWF/co2js'

Would this be an ok experimental first step, to see how easy it might be to extend co2.js to work in impact framework pipelines?

it looks like the code that calls CO2js is in this part of the plugin repo:

https://github.com/wr24-greenit/if-webpage-plugins/tree/main/src/lib

This might also be nice way to support some of the new parameters that @fershad merged in recently that you mentioned were a bit harder to use until that change was made.

👍 ?

I'll wait for @fershad to chime in, as he's more familiar with CO2.js than I am these days, and I reckon he'd likely cast an eye over any PR made

[mrchrisadams]

oh, @alexzurbonsen - I misread your initial question, sorry!

You're asking about starting with adding some docs, so it's much simpler to start using co2js and impact framework together, right? We have a tutorials section in the developer docs repo links below:

https://github.com/thegreenwebfoundation/developer-docs/

And specifically here's where the tutorials are:

https://github.com/thegreenwebfoundation/developer-docs/tree/main/src/docs/co2js/tutorials

That should give an idea of what the code looks like for adding docs.

[alexzurbonsen]

Hey @mrchrisadams, thanks for your replies! 1) True, my initial question was about adding docs because I figured that is a simple way to make a connection between the usage of co2js in the IF and also the measure webpage plugin where it is alreadys used. Thanks for the pointers on this one. Would you agree that this is a worthwhile approach or would you suggest a different path?

2) Responding to your first answer:

Is this sort of how it works?

Yes, I think you got that right. I am just adding a bit of information that might help to clarify: The manifest file defines a so called pipeline, which executes a sequence of plugins, one after the other. Two plugins in that pipeline use functionality from the co2js library:

• co2js plugin (more info below)
• green-hosting plugin (source code) written by me

In general the parameters defined in inputs, config and global config are passed to a plugin. The input parameters are a bit special, because they can be manipulated, e.g. new parameters can be added, by a plugin. In a pipeline, a plugin returns the potentially manipulated inputs as output and the framework passes them as inputs to the subsequent plugin.

As you write as well, the pipeline for webpage measurement makes use of this. The green-hosting plugin for example checks wether a domain is hosted green and adds that information to its outputs, i.e. the inputs for the co2js plugin. Analogously the measure-webpage plugin measures the page weight and passes that to the co2js plugin.

We can ignore the timer-start and timer-stop plugins here because they only add approriate timestamps and durations.

quite a lot of effort has gone into keeping the library small, as well as the number of dependencies low

That's nice and I think there is no need to change. Before I explain why, let me try to clear some potential confusion: I had to modify the co2js plugin that was hosted in the IF unofficial plugins repo because it wasn't allowing me to pass on parameters as I needed it to. That's why the pipeline above does not use the IF's co2js original co2js plugin. But, this could be changed now (I just didn't get to it yet). I opened a PR to change the co2js plugin IF's unofficial plugin repo that was actually merged recently and includes the necessary changes.

So I will change the pipeline to use IF's co2js plugin. And I think that plugin is already pretty much a wrapper around the co2js library, isn't it? In conjunction with the green-hosting plugin these both might actually cover all functionality that the co2js library has to offer (not 100% sure though).

Would this be an ok experimental first step, to see how easy it might be to extend co2.js to work in impact framework pipelines?

Thus, I think there may be no need for extension, unless I missed something? If not, I think the co2js and the green-hosting plugins are already making the co2js library accessible for the impact framework. All that is needed might be information on how to use them there.

What do you think?

[alexzurbonsen]

Addition: I learned that the IF Explorer platform was recently launched. This is a platform where plugins can be registered can thus be easily found by others. I think I will try to add the plugins for the webpage measurement pipeline there as well.

[alexzurbonsen]

One more thing: during the carbon hack I also worked with this team that made quite some efforts to make IF and website measurement with IF more accessible. Here are there results.

E.g. https://github.com/heaversm/carbonhack-if/wiki contains a lot of documentation with a far broader the scope then we are talking about here. But they also included my measurement pipeline. So this stuff could be helpful.

[fershad]

@alexzurbonsen @mrchrisadams thanks for raising this issue & the detailed discussion. I learnt a bit about IF through reading your response Alex, thanks!

Let's keep this discussion for adding a tutorial on how to use CO2.js with Impact Framework. As Chris mentioned, we've got a Developer Docs website where we keep CO2.js related tutorials (https://github.com/thegreenwebfoundation/developer-docs/)

@alexzurbonsen if it's okay with you, can I transfer this issue to that repository?

Happy for you to start writing something up, perhaps in a Google Doc or some other shareable form. We're doing a bit of work to improve the Developer Docs repo as part of Google Season of Docs, and so when that's ready you might be in a good position to help us confirm that the changes we've made are actually helpful to contributors there.

[alexzurbonsen]

@fershad thanks for your answer. Sure, feel free to move the issue over.

I will start writing something up (but it might take me a while to get to it).

[alexzurbonsen]

@fershad I started to work on this. Can you allow me to push to the developer-docs repo? Apparently I am not allowed to. Thank you.

[fershad]

Hi @alexzurbonsen. It's probably easier if you fork this repository, commit your changes to the fork, and then merge it here via a PR.

[alexzurbonsen]

Sure, I was gonna open a PR either way. I can also follow the forking workflow.