Difficulty tracking Dependabot versions back to SDK updates

[reefdog]

This Dependabot PR bumps @pdc/sdk from 0.9.1 to 0.9.2. But of course those version numbers don't mean anything in the context of this repo. I thought tracking it back to the service repo would illuminate, but service's main branch seems to offer 0.9.1 as the most recent OpenAPI version.

How can an interested integrator see what is contained in a specific update, starting from a Dependabot PR?

[slifty]

So the issue is that the sdk version is not the same as the API version. The SDK is actually a combination of two separately versioned code bases (the API version, but then also the code generation template version). The SDK depends on both sources -- so even if the API version was static there could be a different SDK output.

Some solutions might be:

1. Ditching the compound version and just using the API version as the SDK version. The downside is that this means that our API semver would need to reflect breaking changes from SDK code generation sources -- for instance, if we changed our TypeScript templates in a way that would trigger a major SDK version then we would need to know to bump the API spec a major version... for unclear reasons from the perspective of service.

This complication compounds when we have multiple officially supported languages. We would need to update the API version for every template change / every time we want to build a new SDK for any of them!

2. We could try to generate and release a change log with corrected version number headers for a given language as part of the package build process. This would ideally also include a CHANGELOG for the template itself (e.g. the changes we recently made to use a different build tool). This would be a complex bit of code, but possible to do. I don't know if dependabot would automatically be able to load that changelog but it... might? Either way it would be a useful artifact.

3. We could figure out how to release packages in github alongside npm -- github releases let you add a version and changelog metadata (npm doesn't support change metadata). I believe dependabot would be smart enough to load these, but I don't know for sure. This would still require some fancy logic to collate changes between the service changelog and the (currently non-existent) sdk changelog.

4. We could revisit the question of having a dedicated typescript-sdk repository that gets written to by the service CI / CD. I don't think this would solve our CHANGELOG complexity, but it would at least make it very clear what the canonical change log for the SDK was.

So...

As of now I don't know if we have any great options. I do think that 1 is wrong enough that we should ditch it. I might start with 3 -- and ONLY worry about the service changelog for now -- and see how that works.

[slifty]

Regarding the package releases, this will help: https://stackoverflow.com/a/75679739/159522

auto-generated release notes are based on commits, not changelog, however.

[slifty]

It does look like dependabot is smart enough to be able to pull change log items (which I think will suit us better than release notes). For instance you can see it in this PR: PhilanthropyDataCommons/service#1025

So with that in mind we could either...

1. Create an explicit repository for the typescript-sdk, link to that in our package.json, and issue releases there with whatever change log(s) we want to include in the release.

2. Use a single version for all SDKs.

Otherwise the dependabot / npm version number won't match the github release version number (I don't see a great way in github releases to support multiple types of release, but will keep looking).

With that in mind... I do think it might be worth a second look at a typescript-sdk repository which would exist to host the compiled code of the typescript SDK.