Inconsistencies with version tags

[iNikem]

If you open CHANGELOG file tagged with version 1.3.0 then you see that it does NOT contain a section for 1.3.0 release. Also examples distro example uses javaagent version 1.2.0

How about having repository tagged by a version tag in a state which is completely compatible with that version? Meaning having up-to-date documentation and changelog for that version and having all examples using that version. Yes, it means that releases require a separate PR, but we already have one. Only now we do it post-release, instead of pre-release.

[anuraaga]

Currently we tag the exact commit that built the code as forced by the tooling. With the proposal, we would tag a commit after that which shouldn't have code changes so in practice is very similar. One corner case would be if a PR that updates code is merged between running release build and updating the examples, CHANGELOG. The only way I can think of to solve that is to update examples on main and CHANGELOG, change release flow to always create a release branch, always cherrypick the example / CHANGELOG update into the release branch, and tag the release branch, not main branch. I guess it could be considered ideal, but a lot of machinery

[iNikem]

Wait, what do I miss?

• I want to release next version, 1.4.0
• I make a PR, which updates changelog and examples to reflect the state of (yet unreleased) 1.4.0
• PR is merged
• Now I manually tag the resulting commit on the main branch with v1.4.0 tag
• GHA kicks in, builds and publishes 1.4.0, then build examples against just published version (because examples on that commit are using exact version 1.4.0) as a smoke test.

[anuraaga]

PR is merged

How can we merge this PR? Since 1.4.0 is unreleased, there's no way it could pass with a green build right?

[iNikem]

PR is merged

How can we merge this PR? Since 1.4.0 is unreleased, there's no way it could pass with a green build right?

We don't actually need to build examples in ci workflow. If they usually use snapshot versions, then we can build them in PR, forcing to always update examples alongside the actual changes.

[anuraaga]

If they usually use snapshot versions, then we can build them in PR, forcing to always update examples alongside the actual changes.

Doesn't this mean the tagged commit will have examples pointing to a snapshot build? Since we don't have the published artifact yet until GHA kicks in. Even if examples on main build point at snapshots, it seems like one main goal of this issue is to have those examples pointing at the published artifact of the tag within the tagged commit. Code wise it's probably the same, but we do want the build gradles of examples to point to published versions somewhere I think, whether it's a release branch or main branch.

[iNikem]

Tagged commit will point to 1.4.0 in my example. Because "pre-release PR" sets it so. Yes, to yet unreleased version.

Hm, indeed, this prevents from building examples on every PR :(

My main wish still remains: tag should point to both changelog and examples which correspond to this tag.

[anuraaga]

tag should point to both changelog and examples which correspond to this tag.

Yeah I think this is fair. So while the machinery is a bit annoying, I'd say the best option is the one that cherrypicks into an eagerly created release branch to make sure examples are still built properly.

[iNikem]

I don't understand how cherrypicking will achieve that. Tag is created before version is published. So examples with tagged version cannot be built until version is published. I understand that you proposal to "update examples on main and CHANGELOG" still means updating examples to point to the unreleased version? Or can you provide a list of exact steps?

[anuraaga]

1. Execute release workflow. Publishes JARs. Stop having it add a git tag Creates 1.4.x release branch from release workflow commit
2. PR to update examples / CHANGELOG for this release, merge to main
3. Cherrypick this PR into 1.4.x release branch. Tag the cherrypick commit manually

[iNikem]

• Execute release workflow. Publishes JARs. Stop having it add a git tag Creates 1.4.x release branch from release workflow commit
• PR to update examples / CHANGELOG for this release, merge to main
• Cherrypick this PR into 1.4.x release branch. Tag the cherrypick commit manually

But then tag will point to a different commit that was used to build published artifacts. I think this is a bad thing.

[anuraaga]

I think this is a bad thing.

Oh, I assumed with this issue you were already OK with this :P Because we only cherrypick document / examples, is it that bad? Otherwise I can't think of a good way to have a release tag point to the code that published an artifact and examples that use that artifact, due to the chicken-egg problem.

[iNikem]

We just don't have to run examples before version is published :D If we find a good way for that - all is solved.

[iNikem]

What about this:

1. We configure PR workflow to build examples only if against main branch (I assume this is possible)
2. We create a new branch 1.4.x
3. We do a PR preparing 1.4.0 release against 1.4.x branch, including pointing examples to version 1.4.0
4. After PR is merged, we tag that commit as 1.4.0.
5. GHA kicks in, builds and publishes 1.4.0 version. Also builds examples against now published version
6. We cherrypick PR from 3. to the main branch
7. Now we have 1.4.0 tag to the exactly right commit and we have a ready branch for patch releases

[jkwatson]

I don't think that this workflow will end up working with the nebula plugin. IIRC, the nebula plugin requires the tag for the most recent release to be in the history of the main branch to be picked up. This workflow wouldn't end up with the tag on the main branch's history, and therefore wouldn't get picked up for the proper "next" version during builds.

[iNikem]

I don't think that this workflow will end up working with the nebula plugin. IIRC, the nebula plugin requires the tag for the most recent release to be in the history of the main branch to be picked up. This workflow wouldn't end up with the tag on the main branch's history, and therefore wouldn't get picked up for the proper "next" version during builds.

Damn, this is a good point :(

[trask]

globbing on an item to this issue from https://github.com/open-telemetry/opentelemetry-java-instrumentation/pull/4106/files#r706966994

update our README to not point at the latest version URL to discourage usage

I like explicit versions in docs (and keeping it updated), IIRC we were stuck on how to automate this? maybe we can tack this problem on to #3516 @iNikem?

[trask]

I think this is mostly resolved now via #4248 and using release branch for releases (#4709).

Remaining items:

• Decide if we want to use versioned urls in the docs
  • This would require updating the urls to the new version in the release branch, and then merging those changes into main after the release.
• Decide if we want to request a CLA exception for automatically cherry-picking commits as part of the patch release process
  • This could also allow us to automate the non-patch release process as well, which seems like it would be a win.

[trask]

I think I captured the remaining items in #4714. Will wait for @iNikem to confirm in case I missed something, then we can close out this one.