From 0695a2c85665ddb9e11db3312ac9af795ec5756d Mon Sep 17 00:00:00 2001 From: UTSAV SINGHAL <119779889+UTSAVS26@users.noreply.github.com> Date: Thu, 17 Oct 2024 14:20:14 +0530 Subject: [PATCH] Enhance README for Contributions and Technical Clarity - Improved the introduction to highlight the open-source nature of the project and its goals. - Expanded the contributing section to provide clearer guidelines for developers looking to contribute. - Added detailed instructions for setting up a development environment, including dependencies and project structure. - Clarified data sources and methodology, emphasizing the importance of consumption-based carbon intensity. - Included community support channels for developers, such as Slack and GitHub Discussions. - Enhanced accessibility of information regarding the API and historical data access. --- README.md | 108 +++++++++++++++++++++++++++++------------------------- 1 file changed, 58 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index 5e1b7aac7e..9e0613b4ed 100644 --- a/README.md +++ b/README.md @@ -8,83 +8,91 @@

-A real time and historical visualisation of the Greenhouse Gas Intensity (in terms of CO2 equivalent) of electricity production and consumption around the world.
- app.electricitymaps.com » +A real-time and historical visualisation of the Greenhouse Gas Intensity (in terms of CO2 equivalent) of electricity production and consumption worldwide.
+ Explore the App »

GitHub last commit GitHub release (latest by date) - - - Electricity Maps is released under the GNU-AGPLv3 license. + + License - Join our Slack + Join our Slack - Twitter Follow + Twitter Follow

-![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 CO2/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 CO2/capita number because we only count CO2 for electricity (not for imported/exported goods). -The CO2/capita metric, by involving the size of the population, and by not integrating all CO2 emission sources, is thus an incomplete metric. -CO2 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 -**CO2 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.