0.26.0 broke all the things

[skyzyx]

<arghh>

Confirm by changing [ ] to [x] below to ensure that it's a bug:

• I've gone though the API reference
• I've checked AWS Forums and StackOverflow for answers
• I've searched for previous similar issues and didn't find any solution

Describe the bug

Version of AWS SDK for Go?

v0.26.0

Version of Go (go version)?

go version go1.15.2 darwin/amd64

To Reproduce (observed behavior)

Quite honestly I don't even know where to begin. Things got refactored, moved, removed, etc. Go modules broke. There is no upgrade guide. There is no updated documentation about how things are supposed to work now. Some discussion on the Gitter channel (the one in the README, that nobody from AWS participates in anymore) about how this version broke all the things. What little documentation there is, is impenetrable.

I have been patient. I have been nice. I have tickets that have been open for more than 2 years. At this specific moment in time, I am out of patience.

WTAF?

Expected behavior

• DOC. U. MEN. TATION.
• Upgrade guides when shit breaks, yo.
• Notes in the CHANGELOG and Release Notes about breaking changes.

Additional context

Reviewed the following, looking for a hint of what do to.

• https://docs.aws.amazon.com/sdk-for-go/v2/api/
• https://docs.aws.amazon.com/sdk-for-go/v2/api/aws/external/
• https://pkg.go.dev/mod/github.com/aws/aws-sdk-go-v2/
• https://pkg.go.dev/github.com/aws/aws-sdk-go-v2@v0.26.0
• https://pkg.go.dev/github.com/aws/aws-sdk-go-v2@v0.26.0?tab=overview
• https://gitter.im/aws/aws-sdk-go-v2

This is not a thankless open-source gig. You get paid (adequate) money in exchange for supporting the SDKs you build. All I'm asking is that you actually support it. And if you're not going to, then be up-front about it and say so in the README or move it over to awslabs.

</arghh>

[shahrouzz]

v0.26.0 seems to be missing a lot of features that existed in previous versions: dynamodbattribute missing, paginators are nowhere to be seen. Half the links in the readme is either dead or links to the wrong version.

Breaking changes are expected before v1, thats fine, but but why release a version when functionality existed in previous versions is missing? Did someone release it by mistake?

[ianchildress]

I agree. We have been using the v2 sdk for a long time and have invested heavily into it. We are ok with small breaking changes, that is expected, but this is a massively breaking release with poor documentation and missing critical features. There wasn't even a friendly "heads up, this is what has changed and this is how to get around it".

This was poorly planned and poorly executed. This should have been done in several smaller releases with documentation about what was breaking and how to update our code. This would have allowed teams to make smaller changes to stay inline with the v2 changes. Instead, this will be a massive undertaking to fix everything at once.

We have no confidence that future releases will be communicated well and that the releases will be planned out to disrupt customers as little as possible. I am a very frustrated customer.

[jasdel]

Thanks for reaching out @skyzyx, @shahrouzz, @ianchildress, and sharing your feedback with us about the issues you ran into with the latest updates to the v2 SDK. I've gone through the README.md and cleaned up the links that were not pointing the correct location, and added more descriptive information about the v0.25.0 update.

I also going through and updating the release notes for v0.25.0 and v0.26.0 to add more details on the changes, along with migration guidance. I'll update this issue once those are updated.

For future releases, we will include this detailed information for the releases changes. The future release notes will also include guidance for migrating to the latest version as breaking changes are made.

[jasdel]

Thanks again for voicing the unexpected changes you experience with the v0.25.0 update. We've gone back to and update the v0.25.0 release notes and changelog to include a description of changes that were made to the v2 preview SDK and, guidance for migrating to the latest version.

We will make sure release notes with migration guides are included in the coming releases.

We're excited to get your feedback on the updated SDK design, feature ideas you have, and issues you've run into. There are still several areas of the SDK that needs more documentation, and we are working to get these filled out. When you come across areas of the SDK that you think are confusing, or poorly documented create a GitHub Issue and let us know the issue you had, and how the experience can be improved.

[edwardsmatt]

I'll avoid adding to the previous comments expressing the magnitude of breaking changes are unexpected given this was a minor version bump (even though the SDK is in preview)...

Would you recommend clients of this library remain on v0.24.0 until the SDK functionality settles, or could I expect to attempt to upgrade and achieve the equivalent functionality?

[skyzyx]

Your actions are greatly appreciated.

I would assert that documentation is worth 50% of your grade. Immaculate code and no (usable) documentation is still an F. As a paying customer, a former member of your team, and as someone who has been building customer-facing tools for + with AWS since 2004, I have a heavily vested interest in ensuring end-to-end quality in releases.

I appreciate the actions you've taken now, but what I'm most concerned about is the culture which allowed this to happen in the first place, and a continued nagging worry that the culture will lead to poor-quality releases in the future as we move further away from this singular event. The underlying culture needs to change.

Thank you.

[jasdel]

Our guidance for the v2 preview SDK, is we think the major breaking changes and refactors are in place, and we do not expect radical changes to the public API of the v2 preview SDK moving forward towards its general availability release.

With that said we do expect there will most likely be minor breaking changes to the v2 preview SDK in the coming weeks. If you're application is not customizing the SDK's API Clients and operations with custom middleware, I do think think you'll experience a significance change, or migration path once you've updated to v0.27.0.

We expect the breaking changes to be focused on housekeeping improvements such:

• Moving API client higher level feature packages to their own module. e.g. service/cloudfront/sign to feature/cloudfrong/sign as a module.
• Refactoring the SDK's middleware helpers to have consistent behavior and return errors.
• Audit SDK's exported types to ensure they are intended to be exported #811 Pass over exported APIs to ensure they are intended to be exported. This will mainly focus on SDKs internal behavior and middleware that probably should not of been exported in the first place.
• Improvements to SDK Logging and debug Facilities SDK middleware, API clients, and Config loading #594 Potential refactor to the SDK's middleware and stack API to provide a way to enable logging, while also ensuring that stack debugging can be enabled.
• We are considering moving the github.com/awslabs/smithy-go repo in to the SDK's repo as a Go submodule for better discoverability, and convenience.

Any other significant unplanned breaking changes that are discovered are needed that go beyond this scope we'll communicate via the SDK's CHANGELOG.md as a pending release, and create a GitHub issue calling it out before the change is made.

[gitcos]

Since it has been a couple of weeks, I'm trying to find if there's any good documentation now guiding us on what to do with something that worked fine a month ago but is hopelessly broken now.

Some questions...

Q1: "As a part of the refactoring done to v2 preview SDK some components have not been included in this update. The following is a non exhaustive list of features that are not available." followed by a list of components. Are you telling us, "sorry, if you had code depending on any of these, you're screwed, we took these features away?" or are you saying something else? What are we supposed to do if we have software that depends on any of the things you listed in this section?

Q2: Relocated packages.
github.com/aws/aws-sdk-go-v2/aws/external => github.com/aws/aws-sdk-go-v2/config module

We were using external. This implies existing code using external would work if we just change it to use config instead. But, it does not seem to be a drop-in replacement. Is that a bug, was it intended to be a drop-in replacement just with a new name? Or is there migration work that needs to be done for each of these "relocated" packages? If so, where are the guides for how to migrate from external->config, from ec2metadata->ec2imds, and so on?

[jasdel]

I've created a new GitHub milestone, v1.0 Release Candidate. This milestone contains the set of major items that we think are needed before the SDK can be considered ready for release candidate status.

The features that were removed in v0.25.0 were temporarily removed until they could be refactored to meet the updated v2 SDK's design. This milestone includes several features that were removed in v0.25.0 such as paginators, and presigned URLs, and the DynamoDB utilities. Along with migration and developer guides. This milestone will be a good yardstick to gauge the major tasks remaining.

As these features are made available in the SDK we'll update their associated GitHub issues referenced by the release candidate milestone.

[jasdel]

@gitcos the migration from aws/external to config did include several other intended changes. The v0.25.0 Migration guide for Configuration provides the guidance for migration from LoadDefaultAWSConfig to the new function name of LoadDefaultConfig. With that said, this section was further down, and easy to miss with the Relocated Packages section above.

[github-actions]

This issue has not received a response in 1 week. If you want to keep this issue open, please just leave a comment below and auto-close will be canceled.