Discussion: Split the openems/openems Repository by Technology

1

Hi everyone,

I’d like to open a discussion around the current structure of the openems/openems repository.
As the project grows in complexity and adoption, we may benefit from splitting the repository by technology to simplify development, contribution, and maintenance.

Current Situation

The monorepo currently includes several distinct components:

  • Documentation (AsciiDoc)
  • Backend + Edge (Java 21 / OSGi)
  • UI (Typescript / Angular)

While having everything in one place has worked so far, this setup brings increasing challenges:

  • CI/CD pipelines must handle multiple languages and tools
  • Entry barriers are higher for focused contributors (e.g., frontend-only devs)
  • Git performance (clone, indexing, IDE responsiveness) suffers

Proposed Split: By Technology

As a first step, I suggest splitting the monorepo into three dedicated repositories based on technology:

  1. openems (Edge + Backend)
  2. openems-ui
  3. openems-docs

In a later stage, it could be worth evaluating whether Backend and Edge should also be separated further.

Release Management Considerations

A valid concern is that release management across multiple repos becomes more complex.
However, this can be mitigated with automation (e.g., GitHub Actions, Woodpecker CI, etc.).

On the plus side, smaller repos enable:

  • Faster and independent release cycles (e.g., hotfixes to UI without waiting for backend)
  • Better control over versioning per component

Additional Benefits

  • Faster git clone times and lower disk usage
  • More maintainable and modular CI/CD workflows
  • Clearer repository ownership and responsibilities
  • Easier onboarding for new contributors focused on specific tech stacks

What do you think?

I’d love to hear your thoughts:

  • Do you support the idea in principle?
  • Do you see potential issues or drawbacks?
  • Experience with similar restructuring in other projects?

Let’s discuss! A modular repository structure could be an important step forward for OpenEMS as we continue to grow.

  • Keep the current monorepo
  • Split into multiple repositories
0 voters
1 Like
2

Hi,

nice Idea! If you could also provide some kind of “Support” for Woodpecker CI and how to set it up afterwards - it would be GREAT!

3
  • Do you see potential issues or drawbacks?

I concern decreasing integration test and code agent effectivity by migration to polyrepo. // I’m not against polyrepo. this is just comment.

My feels of openems repo structure is “noisy”. Because many java modules is listed in top level. I think this is difficult to understand system structure (ui, backend, edge, …) for beginners.
My sugguestion of first step of organize is moving these java modules to core/ like ui/.

// As other topics, I want to discuss fems update. currently almost fems update commits are not sepalated by ui and core(backend, edge). This make difficult to fork project maintainance. Because reviewing and merging process needs speciality of technologies(angular, java, …), but current commit is mixing these.

4

Thank you @da-Kai for the initiative!

I share @miettal s perspective: I agree that the current repository layout is confusing and “noisy”; I still generally prefer the mono-repo, as it keeps Unit Tests, Tools, Github Stars, Continuous Integration, etc. in one place.

The reason for the flat directory structure is, that bndtools is not able to properly handle subdirectories. But I asked ChatGPT and it is confident, that this could be solved… (but ChatGPT is always confident, so this would have to be proved by testing, which I did not have time for yet)

ChatGPT on moving OSGi bundles to subdirectories with Eclipsee IDE and bndtools

Yes, you can share a Bndtools workspace via Git, and it’s a common and recommended practice for team collaboration and easier onboarding.

However, to make this work smoothly — especially with custom directory structures and new bundle detection — you need to follow some key best practices when sharing the Bndtools workspace.

:white_check_mark: What to Include in Git

You should commit the following:

1. cnf/ directory

  • This contains your workspace configuration, plugins, repository settings, and build.bnd.

  • Essential for consistent builds and dependency resolution.

  • It must be shared.

2. All bundle directories

  • All folders like:

    edge/core/io.openems.edge.core/
backend/example/io.openems.backend.example/

  • Including:

    • bnd.bnd

    • src/

    • .project and .classpath

    • pom.xml (if present, even if you’re not using Maven)

3. .project and .classpath files

  • These are Eclipse-specific files needed for the project to be recognized and opened properly.

  • They should be committed for all bundles and cnf.

:prohibited: What to Ignore in Git

Use a .gitignore file at the root to ignore build artifacts and local metadata:

Recommended .gitignore:

# Eclipse
.settings/
.metadata/
*.tmp
*.bak
*.swp

# Build outputs
**/generated/
**/target/
**/bin/
**/build/

# Logs and local settings
*.log
*.lock

# OS junk
.DS_Store
Thumbs.db

# Bndtools cache
cnf/cache/

:puzzle_piece: Managing New Bundles

Problem:

If you add a new bundle like edge/optimizer/io.openems.edge.optimizer/, your teammate’s Eclipse won’t auto-discover it unless:

  • They re-import it manually.

  • Or: you commit a .bndrun file or central config that includes a reference.

Solution:

Option 1: Commit a .bndrun file that references the new bundle

This ensures Bndtools recognizes it as part of the run configuration:

-runrequires: \
    osgi.identity;filter:='(osgi.identity=io.openems.edge.optimizer)'

Option 2: Document “Import Existing Projects”

Let team members know they should run:

  • File > Import > Existing Projects into Workspace

  • Point to the workspace root (openems/)

  • Eclipse will pick up any newly added bundles.

Option 3: Use bnd.bnd macros for structured inclusion (advanced)

You can use macros and include rules in cnf/build.bnd to include bundles matching patterns, but that’s more advanced and requires consistent naming.

:light_bulb: Onboarding Experience

To make onboarding as easy as possible:

  1. Clone the repo

  2. Open Eclipse

  3. Open the existing Bndtools workspace (point to openems/)

  4. (Optional) Run “Import > Existing Projects” to ensure all bundles are imported

Consider adding a README.md with onboarding steps:

# OpenEMS Workspace

## Getting Started

1. Clone this repo
2. Open Eclipse with the Bndtools plugin
3. Choose this directory (`openems/`) as the workspace
4. File > Import > Existing Projects into Workspace

:white_check_mark: Summary

You can and should share your Bndtools workspace in Git to:

  • Enable fast onboarding

  • Ensure consistent builds

  • Help teammates catch up with new bundles

Just make sure to:

  • Commit cnf/, bundle folders, and Eclipse project files

  • Ignore build output and local metadata

  • Document how to import projects for new team members

Let me know if you want a ready-to-copy .gitignore or README.md template!

[/details]

@miettal

// As other topics, I want to discuss fems update. currently almost fems update commits are not sepalated by ui and core(backend, edge). This make difficult to fork project maintainance. Because reviewing and merging process needs speciality of technologies(angular, java, …), but current commit is mixing these.

Thanks for this feedback. I know FEMS Backports are not optimal as well. Would it not be possible to merge only subdirectories, e.g. with git sparse checkouts. I am interested to create a documentation on how to optimally create forks of OpenEMS for custom deployments.

1 Like
5

Thank you for replying.

Would it not be possible to merge only subdirectories, e.g. with git sparse checkouts.

I also think this one time, but it seems git merge is the process for all directory tree so it cannot devide by subdirectory by sparse-checkout.
// If I can ignore/ovewrite git history, There are many way of pulling upstream changes. But it will be difficult to trace changes.