Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Enhance README for Contributions and Technical Clarity #7330

Closed
wants to merge 1 commit into from
Closed

Enhance README for Contributions and Technical Clarity #7330

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
108 changes: 58 additions & 50 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,83 +8,91 @@
</h1>

<p align="center">
A real time and historical visualisation of the Greenhouse Gas Intensity (in terms of CO<sub>2</sub> equivalent) of electricity production and consumption around the world.<br>
<strong><a href="https://app.electricitymaps.com">app.electricitymaps.com »</a></strong>
A real-time and historical visualisation of the Greenhouse Gas Intensity (in terms of CO<sub>2</sub> equivalent) of electricity production and consumption worldwide.<br>
<strong><a href="https://app.electricitymaps.com">Explore the App »</a></strong>
</p>

<p align="center">
<img alt="GitHub last commit" src="https://img.shields.io/github/last-commit/electricitymaps/electricitymaps-contrib">
<a href="https://github.com/electricitymaps/electricitymaps-contrib/releases">
<img alt="GitHub release (latest by date)" src="https://img.shields.io/github/v/release/electricitymaps/electricitymaps-contrib"></a>
<a href="https://github.com/electricitymaps/electricitymaps-contrib/CONTRIBUTING.md">
<a href="https://github.com/electricitymaps/electricitymaps-contrib/blob/master/LICENSE.md">
<img src="https://img.shields.io/github/license/electricitymaps/electricitymaps-contrib" alt="Electricity Maps is released under the GNU-AGPLv3 license." /></a>
<a href="https://github.com/electricitymaps/electricitymaps-contrib/blob/master/LICENSE.md">
<img alt="License" src="https://img.shields.io/github/license/electricitymaps/electricitymaps-contrib" /></a>
<a href="https://slack.electricitymaps.com">
<img src="https://img.shields.io/badge/slack-3700%2B-%23126945" alt="Join our Slack" /></a>
<img alt="Join our Slack" src="https://img.shields.io/badge/slack-3700%2B-%23126945" /></a>
<a href="https://twitter.com/intent/follow?screen_name=ElectricityMaps">
<img src="https://img.shields.io/twitter/follow/ElectricityMaps" alt="Twitter Follow" /></a>
<img alt="Twitter Follow" src="https://img.shields.io/twitter/follow/ElectricityMaps" /></a>
</p>

![image](web/public/images/electricitymap_social_image.png#gh-light-mode-only)
![image](web/public/images/electricitymap_social_image_dark.png#gh-dark-mode-only)
![Electricity Maps](web/public/images/electricitymap_social_image.png#gh-light-mode-only)
![Electricity Maps](web/public/images/electricitymap_social_image_dark.png#gh-dark-mode-only)

## Introduction
## Overview

This project aims to provide a free, open-source, and transparent visualisation of the carbon intensity of electricity consumption around the world.
**Electricity Maps** is an open-source project providing a transparent, real-time visualization of the carbon intensity of electricity **consumption** across the globe. The platform processes raw data from public, official sources (government bodies, Transmission System Operators, etc.) to calculate a region's carbon intensity using [our flow-tracing algorithm](https://www.electricitymaps.com/blog/flow-tracing).

We fetch the raw production data from public, free, and official sources. They include official government and transmission system operators' data. We then run [our flow-tracing algorithm](https://www.electricitymaps.com/blog/flow-tracing) to calculate the actual carbon intensity of a country's electricity consumption.
**Get started** by exploring our live application at [app.electricitymaps.com](https://app.electricitymaps.com), or download our mobile app from [Google Play](https://play.google.com/store/apps/details?id=com.tmrow.electricitymap&utm_source=github) or the [App Store](https://itunes.apple.com/us/app/electricity-map/id1224594248&utm_source=github).

_Try it out at [app.electricitymaps.com](https://app.electricitymaps.com), or download the app on [Google Play](https://play.google.com/store/apps/details?id=com.tmrow.electricitymap&utm_source=github) or [App store](https://itunes.apple.com/us/app/electricity-map/id1224594248&utm_source=github)._
## Contributing to the Project

## Contributing
Electricity Maps thrives on community collaboration. We welcome contributions in areas such as:

The Electricity Maps app is a community project and we welcome contributions from anyone!
- **Building new data parsers** for additional countries and regions.
- **Maintaining or fixing existing parsers**.
- Enhancing the **frontend user interface** for better visualizations.
- Improving **data accuracy** and adding new **data sources**.
- Updating **regional capacities** for accurate flow-tracing.
- **Discussing feature ideas** and proposing enhancements.

We are always looking for help to build parsers for new countries, fix broken parsers, improve the frontend app, improve accuracy of data sources, discuss new potential data sources, update region capacities, and much more.
Check out our [Contribution Guidelines](/CONTRIBUTING.md) to learn how to get involved and where your expertise can make an impact.

Read our [contribution guidelines](/CONTRIBUTING.md) to get started.
### Setting Up a Development Environment

## Community & Support
To contribute to the project, you’ll first need to set up a local development environment. You can find detailed instructions in our [GitHub Wiki](https://github.com/electricitymaps/electricitymaps-contrib/wiki). This guide includes information on:

Use these channels to be part of the community, ask for help while using Electricity Maps, or just learn more about what's going on:
- Installing the necessary dependencies (Node.js, Python, etc.)
- Working with the data parsers and flow-tracing algorithm.
- Setting up the web or mobile frontend environment.

- [Slack](https://slack.electricitymaps.com): This is the main channel to join the community. You can ask for help, showcase your work, and stay up to date with everything happening.
- [GitHub Issues](https://github.com/electricitymaps/electricitymaps-contrib/issues): Raise any issues you encounter with the data or bugs you find while using the app.
- [GitHub Discussions](https://github.com/electricitymaps/electricitymaps-contrib/discussions): Join discussions and share new ideas for features.
- [GitHub Wiki](https://github.com/electricitymaps/electricitymaps-contrib/wiki): Learn more about methodology, guides for how to set up development environment, etc.
- [FAQ](https://app.electricitymaps.com/FAQ): Get your questions answered in our FAQ.
- [Our Commercial Website](https://electricitymaps.com/): Learn more about how you or your company can use the data too.
- [Our Blog](https://electricitymaps.com/blog/): Read about the green transition and how Electricity Maps is helping to accelerate it.
- [Twitter](https://twitter.com/electricitymaps): Follow for latest news
- [LinkedIn](https://www.linkedin.com/company/electricitymaps): Follow for latest news
If you need help, feel free to join our community channels or raise a GitHub issue.

## License
## Data Sources & Methodology

We collect raw electricity production and consumption data from a variety of **public, official** sources such as **government websites**, **transmission operators**, and other open APIs. Data sources for each country and region are documented [here](https://github.com/electricityMaps/electricitymaps-contrib/blob/master/DATA_SOURCES.md).

This repository is licensed under GNU-AGPLv3 since v1.5.0, find our license [here](https://github.com/electricitymaps/electricitymaps-contrib/blob/master/LICENSE.md). Contributions prior to commit [cb9664f](https://github.com/electricitymaps/electricitymaps-contrib/commit/cb9664f43f0597bedf13e832047c3fc10e67ba4e) were licensed under [MIT license](https://github.com/electricitymaps/electricitymaps-contrib/blob/master/LICENSE_MIT.txt)
### Why Consumption-Based Carbon Intensity?
We calculate the **carbon intensity of electricity consumption**, not production. This means we assign the emissions to the consumers of electricity rather than the producers. It prevents greenwashing, where governments relocate polluting industries while still importing their energy.

## Frequently asked questions
Read more about the importance of **Consumption-Based Accounting (CBA)** in our [blog post](https://electricitymaps.com/blog/flow-tracing/).

### Data Accuracy & Emission Factors
The carbon intensity figures account for **full lifecycle emissions**, including the construction, operation, and decommissioning of power plants. More details on this methodology are available on the [Emission Factors Wiki page](https://github.com/electricitymaps/electricitymaps-contrib/wiki/Emission-factors).

## Community & Support

_We also have a lot more questions answered on [app.electricitymaps.com/faq](https://app.electricitymaps.com/faq)!_
We encourage you to join our growing developer community to ask questions, share your ideas, or showcase your work:

**Where does the data come from?**
The data comes from many different sources. You can check them out [here](https://github.com/electricityMaps/electricitymaps-contrib/blob/master/DATA_SOURCES.md)
- **[Slack Community](https://slack.electricitymaps.com)**: A lively space where developers and contributors discuss ongoing projects and receive feedback.
- **[GitHub Issues](https://github.com/electricitymaps/electricitymaps-contrib/issues)**: Report bugs, suggest improvements, or request new features.
- **[GitHub Discussions](https://github.com/electricitymaps/electricitymaps-contrib/discussions)**: Collaborate and brainstorm with other developers.
- **[FAQ](https://app.electricitymaps.com/FAQ)**: Find answers to common questions.
- **[GitHub Wiki](https://github.com/electricitymaps/electricitymaps-contrib/wiki)**: Deep dive into our technical methodology, development guides, and more.

## Accessing Historical Data & API

Want to integrate carbon intensity data into your project? We provide an API for both real-time and historical data. Learn more about accessing it via our **[Data Portal](https://www.electricitymaps.com/data-portal)**.

For commercial access or large-scale use cases, visit our **[Commercial Website](https://electricitymaps.com/)** for information on tailored solutions.

## License

**Why do you calculate the carbon intensity of _consumption_?**
In short, citizens should not be responsible for the emissions associated with all the products they export, but only for what they consume.
Consumption-based accounting (CBA) is a very important aspect of climate policy and allows assigning responsibility to consumers instead of producers.
Furthermore, this method is robust to governments relocating dirty production to neighboring countries in order to green their image while still importing from it.
You can read more in our blog post [here](https://electricitymaps.com/blog/flow-tracing/).
This project is licensed under the **GNU-AGPLv3** license since version 1.5.0. You can find the full license [here](https://github.com/electricitymaps/electricitymaps-contrib/blob/master/LICENSE.md). Contributions prior to commit [cb9664f](https://github.com/electricitymaps/electricitymaps-contrib/commit/cb9664f43f0597bedf13e832047c3fc10e67ba4e) were licensed under the [MIT License](https://github.com/electricitymaps/electricitymaps-contrib/blob/master/LICENSE_MIT.txt).

**Why don't you show emissions per capita?**
A country that has few inhabitants but a lot of factories will appear high on CO<sub>2</sub>/capita.
This means you can "trick" the numbers by moving your factory abroad and import the produced _good_ instead of the electricity itself.
That country now has a low CO<sub>2</sub>/capita number because we only count CO<sub>2</sub> for electricity (not for imported/exported goods).
The CO<sub>2</sub>/capita metric, by involving the size of the population, and by not integrating all CO<sub>2</sub> emission sources, is thus an incomplete metric.
CO<sub>2</sub> intensity on the other hand only describes where is the best place to put that factory (and when it is best to use electricity), enabling proper decisions.
## Get Involved

**CO<sub>2</sub> emission factors look high — what do they cover exactly?**
The carbon intensity of each type of power plant takes into account emissions arising from the whole life cycle of the plant (construction, fuel production, operational emissions and decommissioning). Read more on the [Emissions Factor Wiki page](https://github.com/electricitymaps/electricitymaps-contrib/wiki/Emission-factors).
Whether you're fixing bugs, improving our data models, or suggesting a new feature, we encourage developers to contribute to **Electricity Maps** and make a real-world impact in accelerating the transition to greener electricity.

**How can I get access to historical data or the live API?**
All this and more can be found **[here](https://electricitymaps.com/)**.
You can also visit our **[data portal](https://www.electricitymaps.com/data-portal)** to download historical datasets.
### Start Contributing:
- Fork the repository.
- Install dependencies as outlined in the [Contribution Guidelines](https://github.com/electricitymaps/electricitymaps-contrib/blob/master/CONTRIBUTING.md).
- Start building! We look forward to your contributions.