discuss github branching policies

[VladimirAlexiev]

@HarisVranaj @Sveino @griddigit-ci @haihutus

@Sveino wrote

The main branch include all the version of the profiles. We are planning to archive this branch.

Archive the main branch? That's a very unusual policy, because most people care only about the main branch and will checkout only the main branch.

• Not just me:
• @Haigutus also submitted his fix Fix SPARQL HAVING without GROUP BY in two constraint queries #82 to the main branch
• @wenxiaojie1 also submitted Fix IdentifiedObject SHACL path subjects #79 to the main brnch
• Is there any large repo that uses such unusual policy?

It is in principle only relevant to verify the latest version - or even more relevant the version that we are updating.

Right! And isn't the current version in-development here:
https://github.com/entsoe/application-profiles-library/tree/main/CGMES/CurrentRelease

So only the following branches are relevant:

• https://github.com/entsoe/application-profiles-library/tree/cgmes-v3-0
• https://github.com/entsoe/application-profiles-library/tree/ncp-v2-4-2

Once we start validating, we need extra folders to hold scripts and results, eg my
https://github.com/entsoe/application-profiles-library/tree/main/validate
This one goes with main/CGMES/CurrentRelease and main/NCP/CurrentRelease.
It shouldn't be looking at files from different branches.
So do you also suggest to copy the validation scripts into different branches?

In addition could the following become relevant:

• https://github.com/entsoe/application-profiles-library/tree/cgmes-v2-4
• https://github.com/entsoe/application-profiles-library/tree/QoCDC-v4-1-4

Isn't there a conflict between these two:

• https://github.com/entsoe/application-profiles-library/tree/main/CGMES/PastReleases/v2-4 and
• https://github.com/entsoe/application-profiles-library/tree/cgmes-v2-4/CGMES

[Haigutus]

I advise against moving to branch-per-version with no unifying main.

Branches are for development work, not for publishing final immutable versions of a standard.

Use tags for releases.

Keep the current approach: everything in main with clear folders (CurrentRelease / versioned/ etc.).

Possible improvements:

• Add the Current release also under versioned, with its version number
• Consider adding a machine-readable catalog.ttl using the W3C PROF vocabulary to formally describe profiles, versions, and which files implement them. This gives clean linking between releases without relying on folder or branch names. But this should be in addition of folder structure.

Why?

• One source of truth: main (or a tag) gives you the full library in one checkout. No need to know which branch is current.
• Self-contained exports: git archive main or GitHub ZIP of main contains everything. Easy to package and distribute (exactly what is already done for releases).
• Consumers & tooling: Most users and pipelines expect to clone once and see all versions. Branch-per-version forces them to discover/parse branch names and juggle multiple checkouts/worktrees.

Technical problems (examples)

Vendoring / submodules

Downstream projects often need multiple versions at once (transition periods).
Current folders: one submodule add → they get every version under versioned/. Updating is one pointer change.
Branch-per-version: you need multiple submodule entries to the same repo but different branches. This multiplies all the usual submodule pain (gitmodules, manual updates, dirty states on branch switches, etc.). Many projects end up just copying files instead.

Automation & pipelines

Want to test “CGMES v3.0 + specific SPARQL”?
Current: cd versioned/v3.0
Branch model: parse branch names, git fetch origin v3.0, git worktree add, handle defaults, etc. Fragile and more code.

History & changes

Seeing what changed in one profile between two releases is much cleaner with folders in one branch history than comparing divergent version branches.

GitHub / contribution UX

Default branch, Releases, CI defaults, discoverability all assume a useful main. A version branch as default is confusing for new users.

Additional reading

Source	Description	Link
CircleCI Blog	Very clear explanation of tags vs branches for releases. Tags are immutable markers for versions; branches are for ongoing development.	Git Tags vs Branches
Stack Overflow (top answer)	Short and direct: branches can move, so they are bad for marking a released version. Tags are the correct tool because they are fixed.	Tags vs release/beta branches for versioning
Official Git Book	Explains what branches actually are (lightweight pointers for development lines).	Git Branching in a Nutshell
Software Engineering SE	Community consensus that using long-lived branches for different versions/editions of the same thing is generally a bad idea (maintenance overhead, merging pain).	Is it good practice to use branches to maintain different editions?

[Sveino]

While I am not an expert in Git workflows, I believe that the repository structure and governance should ultimately be decided by the person or team responsible for maintaining it over time. We have previously seen contributors introduce structures they strongly preferred, only to leave the project later. Long-term ownership and maintainability are therefore more important than individual preferences.

The discussion about how branches should be used is important, but I think we first need to agree on what the repository represents.

In my view, a repository should normally represent one project that can be developed, built, validated, and released as a coherent unit. It is technically possible to place several projects in one repository, but that does not necessarily make them one project.

I am not opposed to having a main branch. However, main should represent the current development state of the project or projects contained in the repository. It should not contain every historical version.

The OGC GeoSPARQL repository is a relevant example of using version-specific branches. It has a default master branch and separate branches such as geosparql-1.1 for maintaining particular versions. This appears to work well because GeoSPARQL is one project with several versions.

Our situation is slightly different. As I see it, the Application Profiles Library currently contains four related but distinct projects:

• CGMES
• NCP
• QoCDC
• ProfileValidation

These projects are related, but they have different release cycles, governance, dependencies, and potentially different maintainers. For that reason, my preferred solution would be four separate but linked repositories.

I also see Git primarily as the source repository used for development and maintenance. For installation, distribution, or operational use, consumers should normally use published GitHub Releases or equivalent release artefacts rather than selecting a branch.

Another consideration is the maintenance of older versions. My general preference would be to maintain only the latest version. However, we have discussed the need to maintain previous versions and agreed that the repository structure should support this. Version-specific maintenance branches, as used by GeoSPARQL, are one possible solution.

As I see it, we have three main options:

1. One repository and one combined project

   Treat CGMES, NCP, QoCDC, and ProfileValidation as parts of one project. The main branch would contain the latest version of all four, organised in separate folders. Version-specific branches could be created where older releases require maintenance.

2. One repository with separate project and version branches

   Keep everything in the same repository, but use branches to separate both projects and maintained versions. The GeoSPARQL repository provides an example of version-specific branches, although using branches for both projects and versions may become difficult to understand and maintain.

3. Multiple repositories

   Create a separate repository for CGMES, NCP, QoCDC, and ProfileValidation. Each repository would have its own main branch, version branches, releases, validation process, and governance. The repositories could still be clearly linked and coordinated. This remains my preferred option.

I leave the final decision to the team that will take long-term responsibility for maintaining the repositories. My main concern is that the selected structure should be understandable to contributors, support the required release and maintenance processes, and remain sustainable when current contributors leave the project.

[VladimirAlexiev]

decided by the person or team responsible for maintaining it over time

Ok, assigning to @HarisVranaj

related, but they have different release cycles, governance, dependencies, and potentially different maintainers

But there are also dependencies between them (NCP can't be used without CGMES etc).
No matter whether we put them in separate repos, folders, or branches: these dependencies need to be thought out and catered for
(The most vivid example of a broken dependency is that you can't use NCP and CGMES together in ReliCapGrid because of CGMES version number mismatches.)

One repository with separate project and version branches

• @Haigutus makes the point that git branches are not made to hold different versions (tags and releases do that).
• I make the separate argument that branches are not made to hold distinct feature sets or projects.
  If I want to get (the latest) NCP and the CGMES that it depends on, am I supposed to checkout two branches? And then how to put them together??

The GeoSPARQL repository provides an example of version-specific branches

Where do you see this?
https://github.com/opengeospatial/ogc-geosparql/tree/master/spec shows only the normal development/feature/PR branches:

[Sveino]

But there are also dependencies between them (NCP can't be used without CGMES etc).

I agree that there are dependencies between the projects—NCP depends on CGMES, and the validation artefacts depend on both. However, I do not think the dependencies are the deciding factor for the repository structure. The more important consideration is governance.

Projects can be strongly dependent while still having independent release cycles, maintenance, and governance. This is common in many open-source projects. The key question is not whether one project depends on another, but whether they should be versioned and governed together.

In our case, CGMES, NCP, QoCDC, and ProfileValidation are related, but they may evolve at different rates, have different release schedules, and could also have different maintainers. That is why I think repository organisation should primarily follow the governance model rather than the dependency graph.

If the decision is to keep them in a single repository, that is perfectly reasonable, but I believe the rationale should be that we want to govern them as a single project—not simply because they have technical dependencies.

You should have scrolled a bit down..

The OGC GeoSPARQL repository provides one example of using version-specific branches (geosparql-1.0, geosparql-1.1, geosparql-1.2, geosparql-1.3). The accompanying documentation even refers readers to the "GeoSPARQL 1.1 Branch" for the resources of that version.
I am not suggesting we should necessarily follow the GeoSPARQL approach, only that maintaining released versions on dedicated branches is an established pattern used by other standards organisations.
We have allready decided to follow version-specific branches in https://github.com/entsoe/relicapgrid/tree/cgmes-3.0_ncp-2.4_tc-1.1

[HarisVranaj]

Hello ,
we discussed with Chavdar and Svein.
our proposal

1. Create a new ProfileValidator GitHub repo
   1.a Copy PROV-AP-CIM into the ProfileValidator + Vladimiar and Kristjan validation code
2. Leave the current ApplicationLibrary (as is - this is used for publication of historical)
3. Copy the CGMES 3.0 to CGMES-Project in a new defined structure, create a branch for archive and create CGMES 3.1 - https://github.com/[entsoe/cgmes-project](https://github.com/entsoe/cgmes-project)
4. Copy the NCP 2.5 to NCP-Project, archive the branch, and created NCP 2.6 - https://github.com/[entsoe/ncp-project](https://github.com/entsoe/ncp-project)
5. Add a validationResult in both CGMS-Project and NCP-Project that include the result of the agree validation from the ProfileValidator

@VladimirAlexiev ; @Haigutus does this make sense ?

[VladimirAlexiev]

@Sveino thanks for pointing me wrong about GeoSPARQL!

They got a complex thing going on there:

• 1.0 branch is 57 commits ahead of and 637 commits behind master.
• 1.1_old branch is 103 commits ahead of and 639 commits behind master.
• 1.1 branch is 93 commits ahead of and 395 commits behind master.
• 1.2 branch doesn't really exist
• 1.3 branch is 350 commits ahead of and 392 commits behind master.

I guess the purpose is to be able to fix bugs in older releases while continuing heavy feature work on new (upcoming) releases.
But how will they deal with these 57+103+93+350 commits ahead of master? (Ok, I should take a union not a sum, but it's propbably about 400 commits).
@situx and @nicholascar can you enlighten us about this organization?