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.

[alexzurbonsen]

@fershad I reworked the tutorial. IF released a matured version last week. As we already discussed, the manifest changed a lot, which also required changes in the plugins. I already did all that back then. I made the manifest file of the tutorial a bit simpler, which is nice I think. I adapted the instructions accordingly.

Also adapted links.

I am about to publish the plugins on npm (probably within the next week). If that is done, you should be able to follow the tutorial as it is. (Currently, that wouldn't work because the installation instructions already assume installation via npm is working.)

I'll keep you posted.

[fershad]

@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.

Thanks @alexzurbonsen . Sorry for not getting around to this earlier, we've got a few projects happening simultaneously at this time which are taking up a lot of our time.

Since you've reworked the tutorial, and a ready to publish the plugin let's proceed with that. What we can do later this year is fork the plugin & then maintain that fork going forwards. You can then update your repo & published plugin to point to that fork. Does that sound like a sensible approach, given that we'd probably not be able to put too much time into this until later in February?

[alexzurbonsen]

@fershad Yes, let's go with the approach that you suggested. I also had something similar in mind, when reworking the tutorial.

[alexzurbonsen]

@fershad the package is published. You can now install it with npm install -g @tngtech/if-webpage-plugins - so the tutorial should finally work.

[fershad]

Thanks @alexzurbonsen . We're busy on another project at this time, but I'll take a look at this PR and the docs update sometime next week.

[fershad]

@alexzurbonsen thanks so much for this!

I've read through the content and tried out the code - it works really well. I'm happy to publish this.

I have raised on issue and PR for the CO2.js plugin to rename the output to avoid confusion about what it represents. That's not a blocker for publishing this, but when that's merged & released please tag me so I can update these docs.

[alexzurbonsen]

@fershad Great to see it online. :) Thanks for the work that you put in as well!

And thanks for issue and PR, I am taking a look now.