Auto-update sub modules without a version (opentelemetry-java-example, opentelemetry-go-contrib, community, ...)

[svrnm]

follow up to #5610

We currently have automation for updating sub modules based on the upstream version update, e.g. if the spec goes from 1.3.8 to 1.3.9 we get an automated pull request that requests an update.

This does not work for repositories that do not have a versioning. Those are:

• community
• opentelemetry-java-examples
• opentelemetry-go-contrib (which now holds the Go example code, needs to be fixed independently)
• other future repos that hold code snippets

As of today we need to have them updated manually, so we wouldn't know if there is a drift in content.

There are three potential solutions to that:

1. Add versions to those repositories
2. Update them on commit to the repository
3. Update them if certain files/folders got updated

While option (1) would be the one with least effort on our end, this is not going to work for all the repos. Especially the community repo has no concept of when a "version" should be released, except we go for a monthly/quarterly pseudo release as we do it for this repo.

Option (2) will be to noise, since all those repos get updated frequently.

Option (3) is worth exploring and my preference as of now. If we can define which files we track, we will only have a few updates from time to time, e.g. for the community repo we would need to track a few of the markdown files, like the "mission-vision-values.md". Those files get updated "a few times per year". The java-examples-repo had 20 commits to the doc-snippets folder since June, https://github.com/open-telemetry/opentelemetry-java-examples/commits/main/doc-snippets, most of them have been version bumps following java releases

cc @jack-berg @chalin @pellared @IgorEulalio

[jack-berg]

There are three potential solutions to that:

What about a 4th option where we add a github action to manually update a particular submodule to the latest for a particular branch?

[chalin]

What about a 4th option where we add a github action to manually update a particular submodule to the latest for a particular branch?

Atm, I'd suggest that we do that entirely manually. Personally, I'd prefer devoting my time to switching to the JS versions of the code-excerpt tools (i.e., the next step of #1635) so that we can have an easier time integrating code-excerpt checking for all (CI and developers), than to work on another GH action.

In the case of git submodules that serve to feed code-excerpts, IMHO it doesn't really make sense to "Auto-update sub modules without a version" until npm run code-excerpts can be (easily) run as a part of CI. (I don't want to bring in the Dart tooling for that.)

So I'd put the problem raised by this issue on hold for now. That is, let's continue update the submodule pin fields manually for those submodules that aren't synced automatically.

We can then deal with the problem on a case-by-case basis when there is a strong enough need / motivation. Remember that support for code-excerpts (at least until #1635 is fully implemented) is still experimental.

As for the community repo, I strongly feel that it is unreasonable to have the entire repo as a submodule only because of two files, whose canonical place should IMHO be in this repo (with back links from those community files into the corresponding OTel website pages, if we want to preserve the pages in the community repo; otherwise, just delete them and update references in other community repo pages accordingly). WDYT?

In my experience on other projects where example source-code excerpts were synced from other repos, the preference was for manual updates. Maybe the Java examples repo should be versioned in a manner to match the Java SIG releases. Just a though.

[jack-berg]

Atm, I'd suggest that we do that entirely manually.

I'm fine with manually updating it for now.

Maybe the Java examples repo should be versioned in a manner to match the Java SIG releases. Just a though.

That's interesting and potentially useful to be able to go back and see how the examples work at different versions. Not a priority of mine, but I like the idea.

[svrnm]

Atm, I'd suggest that we do that entirely manually. Personally, I'd prefer devoting my time to switching to the JS versions of the code-excerpt tools (i.e., the next step of #1635) so that we can have an easier time integrating code-excerpt checking for all (CI and developers), than to work on another GH action.

Makes sense, so let's wait for #1635 then.

As for the community repo, I strongly feel that it is unreasonable to have the entire repo as a submodule only because of two files, whose canonical place should IMHO be in this repo (with back links from those community files into the corresponding OTel website pages, if we want to preserve the pages in the community repo; otherwise, just delete them and update references in other community repo pages accordingly). WDYT?

Eventually I want to source more files from the community repo, not having them in sync properly is one of the reasons why I never touched on that. Also one of those files (mission, vision, values) is owned by the GC and belongs into the community repo, I remember that we had a lengthy discussions around that), not sure what the other file was?