awslabs / awslabs/aws-encryption-sdk-specification

Clarify what an "incompatible API change" is for a specification

Open
#173 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
37
Forks
27
PR merge metrics
No merged PRs in 30d

Description

Our [versioning document](./VERSIONING.md) states:

"We follow Semantic Versioning.

Given a version number MAJOR.MINOR.PATCH, increment the:

MAJOR version when you make incompatible API changes,

..."

Incompatibility is a little unclear here, though, and may be stricter than we are accustomed to when it comes to shared libraries.

From the perspective of a customer of an ESDK, adding a new optional input parameter is not a breaking change. But from the perspective of an ESDK implementation, it is, since the implementation is now "broken" in that it does not match the specification "MUST accept an optional parameter Foo".

The correct analogy might just be that the specification is like a set of interfaces or traits, and changes that break either users or implementors of those concepts should be considered breaking changes.

Contributor guide

Open the contributing guide

Research direction

Start with VERSIONING.md and review the existing Semantic Versioning wording and the issue's distinction between ESDK customers and implementations. Determine the intended definition of an incompatible specification change, then update the versioning guidance so both perspectives are addressed and the document clearly explains what counts as a breaking change.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.