Help make the Shyft better

Shyft is an open-source framework for modelling energy systems, hydrology, and time-series driven applications. Contributions from users, researchers, and developers are very welcome.

The project contains several components implemented in different languages:

  • C++ core libraries implementing the main modelling frameworks

  • Python interfaces exposing the functionality for scripting and analysis

  • Visualization components used in dashboards and operational systems

The C++ core targets modern C++ standards and is designed to be portable across Unix-like systems.

The Python interface exposes the modelling framework to users and provides a convenient environment for scripting, analysis, and integration.

Community Roles

To ensure effective collaboration and clear responsibilities, the Shyft community operates with several roles.

Users

Users apply Shyft for tasks such as:

  • hydrological modelling

  • energy market simulations

  • time-series analysis

  • visualization and dashboards

Users may provide feedback, report issues, or request improvements.

Contributors and Developers

Contributors and developers work on specific tasks such as:

  • documentation improvements

  • examples and tutorials

  • bug fixes

  • new algorithms or model components

Contributions are normally prepared as merge requests based on issues discussed with the maintainers.

Maintainers

Maintainers review and integrate contributions. Their responsibilities include:

  • reviewing merge requests

  • ensuring code quality and consistency

  • maintaining development branches

  • coordinating releases

  • supporting downstream users of Shyft

Owners

Owners have the primary responsibility for the Shyft code base and project governance. This includes:

  • defining project direction and architecture

  • managing project membership

  • coordinating major changes

  • maintaining the infrastructure supporting the project

Development Workflow

Shyft development follows a structured workflow based on a dedicated development branch.

Most development work takes place on the branch:

next-shyft-version

Contributions are submitted as merge requests targeting this branch. Maintainers review contributions and integrate them once they meet the project quality standards.

Detailed guidelines for the development workflow, including issue boards, branch naming conventions, and contribution procedures, are documented in the project wiki.

Branch Structure and Workflow

Shyft development uses a structured branch workflow that separates active development from stable releases and long-term maintenance.

The main branches and concepts are:

  • next-shyft-version

    The integration branch for active development. Contributions are normally submitted as merge requests targeting this branch.

  • master

    The stable branch containing released versions of Shyft.

  • releases/shyft-<major>

    Stable maintenance branches used for downstream backports and production fixes for already released versions.

  • release tags

    Tags such as 34.0.0-1.1 identify a specific released version.

This structure allows Shyft to support both:

  • active development of the next version

  • stable maintenance of already released versions

Development and Release Flow

        flowchart TD

    subgraph DEV["Active development"]
        F["feature branch<br/>initials/issue-short-text"]
        MR["merge request<br/>target: next-shyft-version"]
        N["next-shyft-version<br/>development integration"]
        TR["tracking MR<br/>Draft: Next shyft version"]
    end

    subgraph REL["Release flow"]
        M["master<br/>stable released history"]
        T["release tag<br/>e.g. 34.0.0-1.1"]
    end

    subgraph STABLE["Stable maintenance"]
        R["releases/shyft-34<br/>backport branch"]
        B["backport fixes<br/>e.g. 34.0.1-1.1"]
    end

    F -->|"open MR"| MR
    MR -->|"review + merge"| N
    N -->|"maintainers update"| TR
    N -->|"release preparation"| M
    M -->|"tag release"| T
    M -->|"create stable branch"| R
    R -->|"bug-fix backports"| B

Shyft development, release and stable maintenance workflow

Workflow Explanation

Typical development work starts from an issue.

A contributor or developer creates a feature branch, for example:

sih/1234-fix-cache-lock

and opens a merge request targeting:

next-shyft-version

Maintainers review the contribution and, when accepted, merge it into next-shyft-version.

Tracking Merge Request

Shyft uses a dedicated tracking merge request for the development branch:

Draft: Next shyft version

This merge request acts as the continuously updated overview of what is planned for the next release.

Maintainers update it with:

  • merged issues

  • improvements

  • fixes

  • compatibility notes

  • breaking changes, when relevant

This makes the planned release visible to contributors and downstream users.

Release Creation

When the next release is ready, the maintainers and owners prepare the release by merging next-shyft-version into master.

A release tag is then created on master, for example:

34.0.0-1.1

This tagged commit becomes the basis for the official release artifacts.

Stable Maintenance and Backports

For downstream users and maintainers operating stable environments, Shyft may also maintain release branches such as:

releases/shyft-34

These branches are intended for controlled backports of important bug fixes without introducing new features.

Typical examples are fixes released as:

34.0.1-1.1
34.0.2-1.1

This allows downstream maintainers to stay on a stable major release while still receiving important corrections.

Why This Workflow Is Used

This workflow provides several important properties:

  • contributors have a clear target branch for new work

  • maintainers can organize and review incoming changes continuously

  • downstream users can follow upcoming changes in the tracking merge request

  • stable production users can rely on controlled backport branches

  • release creation remains explicit and traceable

Release Tag Format

Shyft release tags follow a structured format:

Major.Minor.Patch-<release-type>.<build>

Examples:

34.0.1-1.1
34.0.2-0.4

The components have the following meaning:

  • Major.Minor.Patch

    The semantic version of the Shyft libraries.

  • release-type

    1 indicates a stable release.

    0 indicates a development or validation build.

  • build

    Incremental build identifier used when creating multiple builds of the same version during testing or release preparation.

Stable Releases

A stable release uses the format:

Major.Minor.Patch-1.1

Example:

34.0.1-1.1

Stable releases correspond to officially signed release artifacts.

Pre-Release Validation Builds

During release preparation or when verifying fixes for downstream users, pre-release builds may be created using:

Major.Minor.Patch-0.<build>

Example:

34.0.2-0.4

These builds allow downstream projects to verify compatibility before the final release is published.

Once validation is complete, the final release tag is created.

Example:

34.0.2-1.1

Project Wiki

The Shyft GitLab wiki contains detailed information about:

  • development environment setup

  • contribution workflow

  • issue board usage

  • branch naming conventions

  • release workflow

See the project wiki for the latest development guidelines:

Shyft Wiki

Communication

Shyft developers communicate through Matrix channels and GitLab discussions.

See the Contact section for information about how to request access to the developer communication channels.

Reporting Issues

If you encounter problems or unexpected behaviour, please report them through the GitLab issue tracker:

https://gitlab.com/shyft-os/shyft/-/issues

Clear bug reports with reproducible examples are extremely helpful and greatly improve the ability to diagnose and fix issues.