Template Fragments UI: allow user to optionally choose the master/main branch of a template

chrisrueger commented 1 month ago

Based on discussion here which is the 1st 3rd-party workspace-template contribution 🎉 🥳 .

see also https://bnd.bndtools.org/chapters/620-template-fragments.html#providing-template-fragments-as-a-developer

Situation

We require 3rd-party contributors to provide workspace-template coordinates to a specific commit SHA (3rd-party means a non-bndtools github organisation). This is to provide some kind of predictability so that users always get the same template content at the time when the PR for the template was approved.

Problem

Quoting @mnlipp here:

The question is, whether this is the best approach for the "bndtools/workspace-templates" project. Contrary to the "built-in" samples, my template references a versioned jar. This implies that every time I upgrade the plugin, a new PR is required here, creating a (limited) workload for the maintainers (you, obviously). This might apply to other future contributions as well.

I think this is a valid point / concern and the goal of this issue is to collect ideas how to handle this situation going forward.

Ideas

One idea is to provide a specific commit SHA as a default, and an alternative branch as an option which the user has to consent.

e.g. a specific commit SHA template reference looks like this:

mnlipp/de.mnl.osgi/tree/b96e0a8877bad1c68cdc050d5854829253ef63bb/de.mnl.osgi.bnd.repository/workspace-template; \
        name=IndexedMavenRepository; \
        description="Provide an OSGi repository derived from a subset of one or more maven repositories"

which basically points to: https://github.com/mnlipp/de.mnl.osgi/tree/b96e0a8877bad1c68cdc050d5854829253ef63bb/de.mnl.osgi.bnd.repository/workspace-template

e.g. we could modify the UI to optionally give the user the option to chose the master/main branch of a template (assuming master/main is a branch which is automatically up-to-date when the 3rd-party contributor makes changes vs. a commit SHA which is a fixed version at a specific point in time)

e.g. the alternative would need to point here: https://github.com/mnlipp/de.mnl.osgi/tree/master/de.mnl.osgi.bnd.repository/workspace-template

But for this the template author should be able to specify this alternative option (e.g. the workspace-template definition would need to provide e.g. the name of the main-branch (some call it master some main) (TemplateInfo / TemplateID classes)

In https://github.com/bndtools/bnd/pull/6285 I added an "Author" column to the template dialog. So maybe this screenshot there could serve as a base for discussion:

@pkriens thoughts?

pkriens commented 1 month ago

The SHAs are a pain in the ass, yes you need a PR for each change. However, this is a direct line of attack for people using it. Second, and this is maybe almost as important you kill repeatable builds. A build might work today but then the repo gets changed and it wont tomorrow. This is especially bad for projects that are a in static mode. Not a lot of development but still popular. when they finally do something, suddenly they have to fix lots of dependency issues.

So I have sympathy but I think we need to use SHAs. Maybe even for our own repos.

@bjhargrave ?

mnlipp commented 1 month ago

you kill repeatable builds

Maybe I haven't fully understood the mechanism yet. But from the description, I am under the impression that the fragments are copied into the workspace/project when it is created.

During workspace creation there is a wizard where one can select template fragments via checkboxes.

So once I have created my workspace, a change of a fragment won't be propagated into my workspace. (Which also implies as a drawback that I have to do any required upgrades myself, e.g. if required due to a new bnd version.) So existing builds should be repeatable even if new workspaces are (silently) created with an updated version of the fragment.

chrisrueger commented 1 month ago

I think we need to use SHAs. Maybe even for our own repos.

Ok, that would also work for the idea I outlined. So let's say we always use SHA (for our own and 3rd-party), the question is: Should we have an an option to let the use choose another master/main/SNAPSHOT version ("the bleeding edge mode")? I think this is similar to how we provide bndtools builds (released version vs snapshot) If yes, how could this be defined in the template definition?

E.g. staying on the example:

mnlipp/de.mnl.osgi/tree/b96e0a8877bad1c68cdc050d5854829253ef63bb/de.mnl.osgi.bnd.repository/workspace-template; \
        name=IndexedMavenRepository; \
        description="Provide an OSGi repository derived from a subset of one or more maven repositories";\
        snapshot: mnlipp/de.mnl.osgi/tree/master/de.mnl.osgi.bnd.repository/workspace-template#master

Note the snapshot field I added which points to https://github.com/mnlipp/de.mnl.osgi/tree/master/de.mnl.osgi.bnd.repository/workspace-template

This would:

Let the developer specify a default version (SHA) and an additional "latest" / snapshot version.
let the user decide which to use (default would be the first SHA version (still to be discussed how that should look like in the UI)

bjhargrave commented 1 month ago

So I have sympathy but I think we need to use SHAs. Maybe even for our own repos.

@bjhargrave ?

I am not up on how templates work here, so I cannot provide any useful advice.

chrisrueger commented 1 month ago

@pkriens @mnlipp I pushed my suggestion above to the PR and added an updated screenshot to the description. There you can choose the version of the template (default or snapshot)

https://github.com/bndtools/bnd/pull/6285#issue-2541999924

chrisrueger commented 1 month ago

We discarded the snapshot version idea. I updated PR description accordingly.

bndtools / bnd