[WIP] add tutorial on how to use CO2.js within IF

[alexzurbonsen]

Triage

Related issue/s

Please list below any issues this pull request is related to.

• Add docs for usage of co2js within the impact framework #59

Describe the changes made in this pull request

As clearly as possible, describe the changes made in the pull request. You should at least detail "what changes have been made" and "what the results of these changes will be".

[alexzurbonsen]

@fershad This one is not really finished yet, but I want to open it up for review as early as possible.

E.g. I have never used gitpod before and I am wondering if you want to include this here as well?
Also there is already a bunch of explanations that can already be reviewed.

But:

• the installation method for my plugins is not practical. Need to publish to npm eventually I guess.
• if-unofficial-plugins need another release before the described installation method is going to work (if you would want to test running the manifest file you would have to clone the current main branch of the if-unofficial-plugins repo, and run npm install && npm link

[fershad]

Hi @alexzurbonsen thanks for this. I've merged in some redesign work we did on the site late last month.

I'll go through the documentation tomorrow, but:

• Gitpod, no problem not having that.
• Are the other two installation items you mentioned still blockers for this, or could we go live with it & update later as things evolve?

[fershad]

Hi @alexzurbonsen. I made a few text changes to the tutorial, and tried to run through it myself. I was getting a warning that I need to update to the latest manifest format, however when I tried this I got some errors around "green-web-host" parameter is required.

Could you please help update the example manifest to the latest version.

Once that's done I'm happy to merge this tutorial.

[alexzurbonsen]

Hi @fershad thanks for going over the text! Looks good. Pushed some minor changes.

I think the issue you are getting is because you used the co2js plugin from the if-unofficial-plugins repo.
They haven't come around with another release as far as I can see. Currently, the necessary change that deals with the green-web-host parameter is only available on main.

To make it work you would have to uninstall the globally installed version

# verify it is there
npm -g list
# uninstall
npm uninstall -g @grnsft/if-unofficial-plugins

and then get an installation of current main:

git clone https://github.com/Green-Software-Foundation/if-unofficial-plugins.git

and inside the cloned repo

npm install
npm link

This should fix the issue.

But I am not sure that is the state we want it to be when you publish the tutorial? We could also ask the IF folks if they are planning to do another release soon.

[alexzurbonsen]

I am not sure about the version conflicts of the manifest file. I had that as well previously but cannot reproduce it now. What did you do to fix it?

[alexzurbonsen]

Hi @fershad and @mrchrisadams ,

I was playing around with the plugins again and realized that the plugin interface changed substantially in the latest version of IF.

1. I will need to refactor the plugins a lot.
2. Who is owning the co2js plugin now? The if-unofficial-plugins repo has been deprecated. There is an info text saying that the plugins have been handed over to external owners. (I need a refactored version of that as well, for the pipeline to work. If it didn't happen yet, I guess I will refactor it sooner or later.)

[alexzurbonsen]

@fershad, @mrchrisadams Good news: I refactored the plugins, including the co2js plugin.

There is a new and little bit improved co2js plugin at https://github.com/TNG/if-webpage-plugins/tree/main/src/lib/co2js
It now supports the latest co2js version and the SWD model v4.

But I believe this does not need to be owned by our org. Would you be open to owning it in a if-co2js-plugin repo in your org?

[fershad]

Hi @alexzurbonsen, thanks for this. There were some conversations a while back about the ownership of the plugins and stuff. I'm not sure what the resolution to that was, I'll check with @mrchrisadams and we'll get back to you.

I think those updates might also help unblock some of the issues I was having running through the tutorial. I'll set aside some time to try again later on this week.

[fershad]

@alexzurbonsen I spoke to @mrchrisadams about this, and we'd be able to own the repo. If there's still some things in the readme or code that need tidying up for the new spec, then could you take care of that before transferring ownership to our org?

[fershad]

Hi @alexzurbonsen I'm still struggling to get this working on my end as I walk through the tutorial.

After going through the steps, when I run the if-run command I get an output file generated with a status: success value. However, there are no dependencies listed in the output, and there's not outputs block either. It gives the impression that the script is executing but not performing any steps.

When I go into the @tngtech/if-webpage-plugins repo though and run one of the example manifest files, everything works okay.

Are there some more steps that need to be updated in the instructions for this guide?

[alexzurbonsen]

Hi @fershad, I didn't touch the tutorial yet. But I guess something will have to be updated there as well.
I am about to publish the if-webpage-plugins on npm. That would simplify installation instructions a bit. Thus, I am waiting for that.

As for the co2js plugin: that's nice. I have cleaned everything up to the best of my knowledge. Also added a note, that it was tested with IF v0.7.

[alexzurbonsen]

@fershad It took some time to get the package through internal processes, also wasn't highest prio. But I am close to publishing now. Before doing that, can we move the co2js plugin to a repo you guys own? Would be nice if we do this before I am publishing it on npm I guess.