Welcome to the Electricity Maps open source contribution repository.
Any and all contributions however big or small are welcome.
This repository and by extension its community have adopted the Contributor Covenant v2.1 as its code of conduct. If you have any questions about the code of conduct or feel the need to report an incident you can do so by emailing us at codeofconduct@electricitymaps.com. For the full code of conduct see CODE_OF_CONDUCT.md.
We use the GNU Affero General Public License v3.0 for this repository, check the LICENSE.md file details about what exactly this entails. Contributions prior to commit cb9664f where licensed under MIT license
There are several ways to help out without coding, these are primarily:
- Opening issues for bugs.
- Opening issues for data problems.
- Opening and/or participating in discussions about new data sources, features, and more.
- Opening issues when capacity data sources have been updated or changed.
- Finding new data sources, wiki page: Find data sources
- Verify existing data sources, wiki page: Verify data sources
- Adding new or updating our existing translations, wiki page: Translating app.electricitymaps.com
- And more!
Note Take a look at the wiki pages for more detailed instructions
Static information about zones and exchanges are located at config/zones and config/exchanges respectively. The zone configurations hold information such as the installed capacity, which parsers to use, fallback mixes, contributors and other keys that are required by our frontend and internal systems; and while similar the exchange configs hold the the location, capacity, direction and parsers required.
To get started with editing the parsers use the following steps:
- Run
poetry install -E parsersto install all needed dependencies. - Use
poetry run test_parser ZONE_KEYto test any parser changes.
Note: This requires you to have Python 3.10 and Poetry installed, you can see their respective installation guides here:
For more detailed information about parsers specifically you can look at the parser README located at parsers/README.md with specific information about the parser functions located in the parser/example folder
For an example of how a parser can look we have an example here:
parsers/examples/example_parser.py
We use black and isort as code formatters for python which is automatically checked in the CI job Python / Formatting.
If this jobs fails and you need to manually format the code you can run poetry run format in the top level of the repository.
Check the wiki page for more details and tips.
To get started with editing the frontend use the following steps:
- Use
cd webto go into the web directory - Then use
pnpm installto get all dependencies installed.
Note: This requires you to have node.js and pnpm installed, you can see their respective installation guides here:
The frontend can be broken down into 2 main parts, the web app built Vite and the mobile app built with capacitor. Both of these share a common code base that is built upon react.
As a result we have a frontend folder structure that looks like this:
mobileapp
├── android
├── assets
├── icons
└──ios
web
├── config
├── cypress
├── geo
├── public
├── scripts
└── src
├── api
├── components
├── features
├── hooks
├── stories
├── testing
├── translation
└── utils
We use Jotai that saves our state in primitive atoms, these live in #TODO: LINK TO ATOM FILE WHEN REWRITE IS MERGED and are then imported in the individual frontend files where it's needed. If you have a need to save the state for a new feature you should add a new atom to this file so we keep everything organized.
The frontend uses ESLint and Prettier as formatters for all code and this is automatically checked in the CI jobs Prettier / Check and ESLint / Check.
If these jobs fail and you need to format the code you can run yarn lint --fix in the /web folder to do so.
Check the wiki page on formatting for more details and tips.