Type of versioning? Semantic?

[breuerfelix]

Hey,

we are trying to figure out what type of versioning this repository uses.
There was a major update from 6 to 7 to 8, without any breaking changes.

Also there are minor updates with breaking changes and minor updates with 1 to 30 breaking changes. We are having trouble figuring out when breaking changes occur and when not.

Is there a ruleset on when patch, minor and major versions increase?

[flubbes]

For example take a look at these breaking changes we saw in minor releases:
https://github.com/pulumi/pulumi-gitlab/releases/tag/v8.10.0
https://github.com/pulumi/pulumi-gitlab/releases/tag/v8.9.0

In the case this repository doesn't try to follow semantic versioning, people need to configure their renovate or dependabots accordingly for this particular package.

[corymhall]

@flubbes this repository follows the same versioning schema as the upstream terraform provider. We release major versions when the upstream provider releases a new major version. We also try to mitigate any breaking changes that may effect Pulumi, but not the upstream provider. Typically the list of "breaking" changes that are listed in the release notes relate to SDK level breaking changes and should typically not effect most users.

Were there any specific issues that affected you in these recent releases that we could try and address? To give some additional commentary to the changes in the two releases you mentioned:

• v8.10.0 - This is the type of change that may be breaking, but is usually not in most cases. There were a couple of new properties added to the return type of the function, so while the interface did change, existing users code should not break.

• v8.9.0 - This had a couple of different changes that were labeled as breaking because they changed the SDK interface, but in most cases were not breaking.

  • Upstream removed some input properties that were not valid input properties.
  • Additional return type properties were added similar to v8.10.0
  • type changed from "number" to "integer" - This change was due to fixing a bug which incorrectly had these properties typed as number when they should have been integer. This change was made to reflect the actual type of the field.

[flubbes]

@corymhall Thanks for the clarification. I'll try to explain the problems we (@breuerfelix is part of my Team at RTL) have had with the current versioning. We fully understand that the source of our problems is currently not the versioning of this repository, but of upstream repositories. But hear us out :)

We understand that aligning terraform-provider-gitlab with gitlab releases makes sense at first glance. But it doesn't really make sense to us. We think the gitlab terraform provider should also use semantic versioning, but that's another story.

See for example the 17.8.0 release of the terraform-provider-gitlab => https://gitlab.com/gitlab-org/terraform-provider-gitlab/-/blob/main/CHANGELOG.md?ref_type=heads#1780-2025-01-16. They know they have breaking changes, and even declare them in the release notes, and don't release a major version to stay aligned with the 17.8 gitlab milestone.

We use the pulumi-gitlab provider with typescript, so we use the package from the npm registry. The npm registry encourages (but does not enforce) semantic versioning. This is probably why we assumed that pulumi-gitlab would also use semantic versioning.

You said "v8.9.0 - This had a couple of different changes that were labeled as breaking because they changed the SDK interface, but in most cases were not breaking". Focus on the "but in most cases were not breaking" part: To us, this is the exact definition of a breaking change. A provider update can break the user's code without changing the code. And since pulumi-gitlab has a lot of users it should also consider the "fewer cases" as important.

We recently updated pulumi-gitlab from 8.9.0 to 8.10.0 and this broke our code because we have several ComponentResources that used to take strings as input for the groupId of GroupMembership. It's worth noting that the ids of GitLab API resources have been very inconsistent in the past. Sometimes they would require it as a string in one resource, but output it as a number in the other. We know that pulumi-gitlab doesn't have any control over this, as most of it is auto-generated from the upstream terraform provider, but we wanted to mention it to clarify that this is a "hot topic".

What we would like you to think about

Use semantic versioning with the pulumi-gitlab provider. You already have schema change detection that can correctly detect any API change that could break the user's code without them doing anything other than updating the provider version.

To us it's a bit odd that this provider is aligning itself with the upstream library, yet it's operating on completely different versions. I think this kind of defeats the whole purpose.

After all, the upstream provider releases a new major version specifically to match the GitLab version. If the Pulumi provider only releases a major version when upstream does, but doesn't align with that version, then it neither matches GitLab nor is functionally accurate.

We understand that there is much more to it than just our point of view coming from using the node sdk, but you and your team can think about it :)