feat: Add commit id into source code url of gem metadata

[thompson-tomo]

Closes #1961

This tweaks the gemspec files so that the source code url now contains the commit which generated the gem. By including this commit id, we can as part of deprecation work remove the source files while having atleast the latest published version of gem pointing to the code used and a readme containing the deprecation

Note the only other change was to update resources/aws/opentelemetry-resource-detector-aws.gemspec so that it was the same metadata as the other gems.

[scbjans]

LGTM

[arielvalentin]

Would using tags instead of SHA be a better user experience?

[thompson-tomo]

Both achieve the same result and experience, tags are nicer for users using github but we would need to extend the CI to be adding tags and using them. The nice thing about commits is that they are always available to both ci/users and can not be tampered with.

[dazuma]

We talked about this in the SIG this week, and there seemed to be a preference to use the release tags. The reasons, besides the fact that URLs are more comprehensible as being tied to a specific release version, are:

• GITHUB_SHA is available in CI (and also, of course, critically, in the release process) but not in local development environments. Thus local testing would fall back to main, meaning local testing and CI testing of gemspecs would yield different results
• Using the release tag would make for more repeatable builds of gemspecs, as every gemspec for a specific release version (i.e. spec.version) would have the same source URL. Whereas if we use the current SHA, any given gemspec created during CI could and probably would be different from the actual released gemspec.

The downsides of using a tag are:

• It is technically feasible to move a tag, whereas it is not for a SHA. (We of course wouldn't expect to do so, but the possibility is there.)
• It is also technically possible for tag creation to fail during the release process. This would, however, mean the release is considered failed and incomplete, and normally we would go through retries or other procedures to make sure it gets properly created in the end.

In my judgment, those are less compelling concerns.

The release tag name is straightforward to compute: #{spec.name}/v#{spec.version}. I'd prefer we use that instead of the SHA.

[thompson-tomo]

The problem you run into with using spec to compute the tag is local development would be generating invalid/untestable urls.

Whereas if we use the current SHA, any given gemspec created during CI could and probably would be different from the actual released gemspec.

It should be pointing to the sha of the commit used in the release hence shouldn't be different.

GITHUB_SHA is available in CI (and also, of course, critically, in the release process) but not in local development environments. Thus local testing would fall back to main, meaning local testing and CI testing of gemspecs would yield different results

If you want This can be addressed by setting an environment variable as part of the rake task and then using this variable.

ENV["GIT_COMMIT"] ||= git rev-parse HEAD.strip if system("git rev-parse HEAD > /dev/null 2>&1")

[robbkidd]

The problem you run into with using spec to compute the tag is local development would be generating invalid/untestable urls.

True. However, we're already generating invalid/untestable URLs in two other spec.metadata fields: changelog_uri and documentation_uri. Both interpolate spec.version to link to content at rubydoc.info that doesn't exist until after the release process builds and publishes the docs for the version being released.

🤔 Until we've got link-liveness-checking of these package metadata URLs included in our test suite—which, again, won't work for docs links until after a version is released—I'm in favor of interpolating the tag name:

- …/opentelemetry-ruby-contrib/tree/main/instrumentation/<cool-gem-name>'
+ …/opentelemetry-ruby-contrib/tree/#{spec.name}/v#{spec.version}/instrumentation/<cool-gem-name>'