Contributing guide#

You’ve discovered a bug or something else you want to change in OpenSTEF — excellent!

You’ve worked out a way to fix it — even better!

You want to tell us about it — best of all!

Below, you can find a number of ways to contribute, and how to connect with the OpenSTEF community.

Ways to contribute#

Do I really have something to contribute to OpenSTEF?

100% yes! There are so many ways to contribute to our community. Take a look at the following sections to learn more.

There are a few typical new contributor profiles:

  • You are an OpenSTEF user, and you see a bug, a potential improvement, or something that annoys you, and you can fix it.

    You can search our issue tracker for an existing issue that describes your problem or open a new issue to inform us of the problem you observed and discuss the best approach to fix it. If your contributions would not be captured on GitHub (social media, communication, educational content), you can also reach out to us on our LF Energy Slack workspace (#openstef channel) or attend our four-weekly co-coding meetings.

  • You are not a regular OpenSTEF user but a domain expert: you know about forecasting, machine learning, energy systems, time series analysis, or some other field where OpenSTEF could be improved.

    Awesome — you have a focus on a specific application and domain and can start there. In this case, maintainers can help you figure out the best implementation; open an issue or pull request with a starting point, and we’ll be happy to discuss technical approaches.

    If you prefer, you can use the GitHub functionality for “draft” pull requests and request early feedback on whatever you are working on.

  • You are new to OpenSTEF, both as a user and contributor, and want to start contributing but have yet to develop a particular interest.

    Having some previous experience with forecasting or energy systems can be very helpful when making open-source contributions. It helps you understand why things are the way they are and how they should be. Having first-hand experience and context is valuable both for what you can bring to the conversation and to understand where other people are coming from.

    Understanding the entire codebase is a long-term project, and nobody expects you to do this right away. If you are determined to get started with OpenSTEF and want to learn, going through the basic functionality, choosing something to focus on (models, feature engineering, evaluation, etc.) and gaining context on this area by reading the issues and pull requests touching these subjects is a reasonable approach.

Code#

You want to implement a feature or fix a bug or help with maintenance - much appreciated! Our library source code is found in:

  • Core forecasting models: packages/openstef-models/

  • Evaluation and analysis: packages/openstef-beam/

  • Core utilities, dataset types, and shared functionality: packages/openstef-core/

  • Examples and tutorials: examples/

  • Tests: packages/*/tests/

Because many people use and work on OpenSTEF, we have guidelines for keeping our code consistent and mitigating the impact of changes.

Code is contributed through pull requests, so we recommend that you start at Start a pull request. If you get stuck, please reach out on the LF Energy Slack workspace (#openstef channel) or join our four-weekly co-coding meetings.

Documentation#

You, as an end-user of OpenSTEF can make a valuable contribution because you can more clearly see the potential for improvement than a core developer. For example, you can:

  • Fix a typo

  • Clarify a docstring

  • Write or update an example

  • Write or update a tutorial

  • Improve the getting started guide

  • Add forecasting domain expertise to documentation

Our code is documented inline in the source code files in packages. Our website structure mirrors our folder structure, meaning that a narrative document’s URL roughly corresponds to its location in our folder structure:

using the library

  • examples/examples/

  • examples/tutorials/

  • docs/source/api/

information about the library

  • docs/source/user_guide/

  • docs/source/project/

  • docs/source/contribute/

Instructions and guidelines for contributing documentation are found in:

Documentation is contributed through pull requests, so we recommend that you start at Start a pull request. If that feels intimidating, we encourage you to open an issue describing what improvements you would make. If you get stuck, please reach out on the LF Energy Slack workspace (#openstef channel) or see our Support page for more ways to connect.

Community#

OpenSTEF’s community is built by its members! You can help by:

  • Participating in our four-weekly community meetings (see Support)

  • Joining discussions on the LF Energy Slack workspace (#openstef channel)

  • Contributing to documentation and examples

It helps us if you spread the word: reference the project from your blog and articles or link to it from your website!

If OpenSTEF contributes to a project that leads to a scientific publication, please cite us following the Citing OpenSTEF guidelines.

If you have developed an extension to OpenSTEF, please consider adding it to our ecosystem or creating a tutorial showing how to integrate it.

New contributors#

Everyone comes to the project from a different place — in terms of experience and interest — so there is no one-size-fits-all path to getting involved. We recommend looking at existing issue or pull request discussions, and following the conversations during pull request reviews to get context. Or you can deep-dive into a subset of the code-base to understand what is going on.

Four-weekly co-coding meetings#

Every four weeks, we host co-coding meetings to work together on OpenSTEF development, discuss project roadmap, and support new contributors. Anyone can attend, whether you’re a seasoned contributor or just getting started. These meetings are a great opportunity to:

  • Get real-time help with your contributions

  • Collaborate on complex issues

  • Learn about the project architecture

  • Meet other community members

  • Discuss upcoming features and priorities

You can find meeting information and calendar invites on our LF Energy wiki page. We encourage joining these meetings to get to know the people behind the GitHub handles 😉.

Good first issues#

While any contributions are welcome, we have marked some issues as particularly suited for new contributors by the label good first issue. These are well documented issues, that do not require a deep understanding of the internals of OpenSTEF and are a great way to get started with contributing to the project.

First contributions#

If this is your first open source contribution, or your first time contributing to OpenSTEF, and you need help or guidance finding a good first issue, look no further. This section will guide you through each step:

  1. Navigate to the issues page.

  2. Filter labels with “good first issue” to find beginner-friendly tasks.

  3. Click on an issue you would like to work on, and check to see if the issue has a pull request opened to resolve it.

    • A good way to judge if you chose a suitable issue is by asking yourself, “Can I independently submit a PR in 1-2 weeks?”

  4. Check existing pull requests and filter by the issue number to make sure the issue is not already in progress.

    • If the issue has a pull request (is in progress), you can ask to collaborate with the existing contributor.

    • If a pull request does not exist, create a draft pull request and follow our pull request guidelines.

  5. Please familiarize yourself with our contribution workflow and ensure you understand the development setup process before starting your work.

Get connected#

When in doubt, we recommend going together! Get connected with our community of active contributors, many of whom felt just like you when they started out and are happy to welcome you and support you as you get to know how we work, and where things are.

Getting help#

If you need assistance:

  • 💬 Slack: Join the LF Energy Slack workspace (#openstef channel)

  • 🐛 Issues: Check GitHub Issues or create a new one

  • 📧 Email: Contact us at openstef@lfenergy.org

  • 🤝 Community meetings: Join our four-weekly co-coding sessions

For more information, see our Support page.

Choose an issue#

In general, the OpenSTEF project does not assign issues. Issues are “assigned” or “claimed” by opening a PR; there is no other assignment mechanism. If you have opened such a PR, please comment on the issue thread to avoid duplication of work. Please check if there is an existing PR for the issue you are addressing. If there is, try to work with the author by submitting reviews of their code or commenting on the PR rather than opening a new PR; duplicate PRs are subject to being closed. However, if the existing PR is stalled and the original author is unresponsive, feel free to open a new PR referencing the old one.

Start a pull request#

The preferred way to contribute to OpenSTEF is to fork the main repository on GitHub, then submit a “pull request” (PR). To work on a pull request:

  1. First set up a development environment by following the instructions in Setting up OpenSTEF for development

  2. Then start solving the issue, following the guidance in development workflow

  3. As part of verifying your changes check that your contribution meets the pull request guidelines and then open a pull request.

  4. Finally follow up with maintainers on the PR if waiting more than a few days for feedback. Update the pull request as needed.

If you have questions of any sort, reach out on the LF Energy Slack workspace (#openstef channel) and consider joining our four-weekly co-coding meetings.