search

Snowflake-Labs / terraform-provider-snowflake

Terraform provider for managing Snowflake accounts
https://registry.terraform.io/providers/Snowflake-Labs/snowflake/latest
MIT License
530 stars 413 forks source link

[Feature]: properly mark breaking changes in release notes #2962

Open andreineculau opened 1 month ago

andreineculau commented 1 month ago

Use Cases or Problem Statement

Latest release 0.94.0 missed adding a migration note.

Category

category:other

Object type(s)

No response

Proposal

While it's great to have a link to the migration notes of the specific version bump, I suspect it's a manual process, and thus error prone.

I'd like to suggest

  1. to always add a static link to https://github.com/Snowflake-Labs/terraform-provider-snowflake/blob/main/MIGRATION_GUIDE.md , no matter if the version bump has or not breaking changes.
  2. to VISUALLY mark which points in the "What's new" section is breaking either via an emoji or a separate section. If you're adhering fully to convention commits, then simply rename the PR from "feat" to "feat!" and it will be marked accordingly

How much impact is this issue causing?

Medium

Additional Information

No response

Would you like to implement a fix?

sfc-gh-asawicki commented 1 month ago

Hey @andreineculau. Thanks for reaching out to us.

We have fixed the release notes for this version (a migration guide has been added). It was an oversight on our part, and we are sorry for any inconvenience.

After reaching V1, we plan to strictly adhere to semantic versioning and may change the release process. We will keep in mind your pointers before that.

sramshaw-yolabs commented 1 month ago

This broken release process is getting very old very fast.

sfc-gh-asawicki commented 1 month ago

Hey @sramshaw-yolabs. Thanks for reaching out to us.

What do you mean by the broken release process?

sramshaw-yolabs commented 1 month ago

@sfc-gh-asawicki Broken may have been a strong word. The Disclaimer describes how this project is being treated as pre 1.0.0 experimental. But the reality is it has been the provider for over 5 years now. While I do understand Snowflake officially took it over at some point (can't recall when, but at least 1-2 years ago?) it is extremely cumbersome on your users when bug fixes, new features, and breaking changes all merged into one release path.

Users want to take advantage of bug fixes and new features, but it is extremely impactful on us when we have repeated sudden work injections to address numerous breaking changes with the only other choice being to pin to a version that may have bugs or lack features we want to use.

As you can see from the terraform registry this provider is extremely well used with over 1 million downloads this month alone.

Maybe you are close enough to 1.0 now that this is all moot point, but I've honestly lost count at how many times I've had to inject work to address the breaking changes that imo should have been forked to a pre-1.0.0 release path months or even years ago.

If at all possible I would request for you to consider the impact on users and slate all of the remaining breaking changes for the 1.0.0 release. This would let people plan for the work to cutover to 1.0.0 as opposed to being surprised every week as to whether there are breaking changes that need to be addressed or not.

Provider Downloads All versions 
Downloads this week
288,962
Downloads this month
1.0M
Downloads this year
7.1M
Downloads over all time
17.7M

Thank you for reaching out.

sfc-gh-asawicki commented 1 month ago

Hey @sramshaw-yolabs. Thanks for the elaborate answer.

After reaching V1, we will definitely change the release process to strictly adhere to semantic versioning (breaking changes will require a major bump).

We have considered the alternatives with the 0.x versions and concluded that we want to avoid a big-bang V1 version. We will change the provider step-by-step with a sequence of breaking changes. It still allows our users to make a big-bang migration themselves by staying on the current version until V1 is released.

It's completely fine to pin to a current version and migrate afterward. I would even say that automatically bumping minors in the experimental (0.x projects) is risky and should be avoided because they can always contain breaking changes.

You are right that pinning to a version limits the use of the newer features/bug fixes. Currently, almost all are added in the context of the redesigned resources, so they still require migrations. It is also possible to set up a separate deployment with the newer provider version to manage only the newly added features.

For the 1M downloads, we have received only three complaints (including yours) about the breaking changes in the 0.x version. We can still reconsider our options. I'll talk about this with the whole team, and we will get back to you. Until then, please pin the version to avoid the biweekly/triweekly migrations.