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 [email protected]. 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 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 web/src/utils/state/atoms.ts 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.
In order for your PR to be accepted and deployed it will need to pass a series of checks, these checks will be defined and explained in the following section of this document.
%%{init: {"flowchart": {"defaultRenderer": "elk"}} }%%
flowchart LR
subgraph idContrib["Electricity Maps contrib"]
direction LR
id1((Open a PR))
id2{First time contributor?}
id3(Await EMaps team CI approval)
id4{Is the CI tests passing?}
id5(Make changes)
id6{Passing review from EMaps team member}
id7(PR is merged)
id8(Deployed to Staging)
id1-->id2
id2-->|Yes|id3
id2-->|No|id4
id3-->id4
id4-->|No|id5
id5-->id4
id4-->|Yes|id6
id6-->|No|id5
id6-->|Yes|id7
id7-->id8
end
subgraph idInternal["Electricity Maps internal"]
direction LR
id9((Automatic PR created))
id10{Are internal CI tests passing}
id11(Make changes)
id12{Passing review from Emaps member?}
id13(Deployed to production)
id9-->id10
id10-->|No|id11
id11-->id10
id10-->|Yes|id12
id12-->|No|id11
id12-->|Yes|id13
end
id7-->id9
In order to do code changes to the Electricity Maps repository you need to fork the repo and make changes in your own fork and then open a pull request (PR) against the Electricity Maps repository.
Once this has been done the automatic and manual review process starts, this consists of manual approval of the CI pipeline if you are a first time contributor, if the CI pipeline passes a team member will review your specific code changes. If they pass all automated tests and manual review from a Electricity Maps Employee it will be merged in our contrib PR. This does not mean it will be automatically de deployed or that the changes will be instantly visible.
If it is frontend changes it will be deployed to our staging environment at https://staging.electricitymaps.com and if there is parser changes these go on to more internal tests that includes both automated test suits and manual reviews. Once everything passes and an approval has been granted a new release will be created that updates the production environment for both the frontend and parser changes.