Merge v0.10.0 work back into main

mrchrisadams commented 2 years ago

This PR brings back the work carried out with @fershad to improve the developer experience and documentation for using CO2.js.

This includes:

[x] switching to import syntax from commonjs syntax in the src directory
[x] making this a hybrid module for using in server side and clientside browser runtimes
[x] updated docs for first use
[x] decide whether to update defaults to use the SWD model not the 1ybte model for carbon calculation, and add warnings
[x] Add links to spreadsheet calcs in documentation, after sanity checking the workings one last time

fershad commented 2 years ago

@mrchrisadams should we output the IIFE version to the /dist folder as well (currently gets built to /public). In this way we can document how people can build the library from source & point them to a single output location with all three versions.

fershad commented 2 years ago

I've created a GitPod configuration file for the project. This builds the different versions & opens the demo in the /public folder when the repo is launched in GitPod.

mrchrisadams commented 2 years ago

Release CO2.js 0.10.x

mrchrisadams commented 2 years ago

Sup @fershad

should we output the IIFE version to the /dist folder as well (currently gets built to /public). In this way we can document how people can build the library from source & point them to a single output location with all three versions.

I think this is a good idea. I had initially thought that it made sense to copy of the iife version it from /dist to /public, so that people could serve just files in the public folder by itself.

But if it's not necessary to do that I'm happy to refer to the iife in dist.

Splitting out the other parts of the project

There are two other items in this PR to be completed:

updated docs for first use
decide whether to update defaults to use the SWD model not the 1ybte model for carbon calculation, and add warnings

Because we already have another inbound PR for updated documentation, and because the shift to the SWD model likely changes some resulting carbon calculations, I'm happy to split these both out. so we can get 0.10.0 published to npm and merged back into main.

I'm happy to support your decision here - if you do, would please either create or link to the corresponding issues so we can queue them up for a future release?

mrchrisadams commented 2 years ago

Oh @fershad - if you do, can you please move the issue about switching the default calculation model to the next milestone, so I know to get the dev work lined up for them?

https://github.com/thegreenwebfoundation/co2.js/milestone/3

mrchrisadams commented 2 years ago

OK, I think once this release is merged in, we'll have some nicer docs for trying out co2.js That would close off the updated docs for first use item in our checklist, leaving just the SWD item before we can merge this into main and release 0.10.0

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

fershad commented 2 years ago

Oh @fershad - if you do, can you please move the issue about switching the default calculation model to the next milestone, so I know to get the dev work lined up for them?

https://github.com/thegreenwebfoundation/co2.js/milestone/3

I've moved that to the 0.11.0 milestone.

mrchrisadams commented 2 years ago

Hey @fershad - I think with the developer docs up, and the switch to SWD as default model bumped to the next release, that we're good to merge this in.

I'm just going to add some notes here to think out loud about the changes.

Expected changes to calcs

The shift to 0.9 to 0.10 should result in minimal changes to calcs, as we shift from gigabytes being 1024 * 1024 * 1024 to being 1000 * 1000 * 1000.

Sanity checking for breaking changes

Any code consuming the co2.js should still work as it did before, as we haven't made any breaking changes to the API.

Downstream consumers

I'll send an email to a few folks I know using CO2.sh, and ask them about running npm install @tgwf/co2@beta as a sanity check before we publish this under the @latest tag.

Being able to point to the updated developer docs, before publishing the updated version to npm ought to help.

fershad commented 2 years ago

Thanks @mrchrisadams I'll add a small update to the README in this PR to point to the docs site.

mrchrisadams commented 2 years ago

Actually @fershad - there's one check we need to make on this before we merge in. I want to sanity check the calcs against a spreadsheet, and document how to do the same, so others can do so as well.

mrchrisadams commented 2 years ago

OK, I've resolved the discrepancies here between the code and the spreadsheet. It was a by product of CO2.js using rounded numbers, and the spreadsheet not using the rounded figures. Merging in.

thegreenwebfoundation / co2.js