Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
148 lines (111 loc) · 7.36 KB

CONTRIBUTING.md

File metadata and controls

148 lines (111 loc) · 7.36 KB

Welcome! 🎉

Welcome to the Electricity Maps open source contribution repository.
Any and all contributions however big or small are welcome.

Links

Code of Conduct

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.

License

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

Getting Started

Non-code contributions

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
  • And more!

Note Take a look at the wiki pages for more detailed instructions

Zone and exchange configurations

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.

Parser guidelines

To get started with editing the parsers use the following steps:

  1. Run uv sync --extra parsers to install all needed dependencies.
  2. Use uv run test_parser ZONE_KEY to test any parser changes.

Note: This requires you to have Python 3.10 and uv installed, you can see their respective installation guides here:

Parser information

For more detailed information about parsers specifically you can look at the parser README located at electricitymap/contrib/parsers/README.md with specific information about the parser functions located in the electricitymap/contrib/parser/example folder

Example parser:

For an example of how a parser can look we have an example here:
electricitymap/contrib/parsers/examples/example_parser.py

Formatting the parsers

We use ruff as a code formatter 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 uv run format in the top level of the repository.

Check the wiki page for more details and tips.

Contribution lifecycle

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.

Overview

%%{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
Loading

Description

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 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.