Hey @gabe.chang, thanks for the feedback, and welcome to the Prismic forums.
Like much of the Open Source community, we follow Semantic Versioning with our version numbers so that users can see what kind of an update each version is.
As Semantic Versioning says, we won’t ship a breaking change outside of major versions, mostly bug fixes and, as you said, adding backward-compatible functionalities. You can safely update your projects within major versions without changes to your code. (It may happen that we accidentally ship a breaking change on a non-major version, despite an abundance of caution. In that case, we consider it a bug and will work to fix it.)
When we go from v5.x.x to v6.x.x we’re trying to make it clear that this upgrade comes with breaking changes, and we often provide migration paths (example). We also try to release new major versions at a slow pace (around once a year) so that everyone is able to follow along. Staying on older major versions, while it might not get you new features to integrate, is perfectly fine, and we release security fixes on them when required.
We may deprecate existing APIs within minor version changes (v6.1.x to v6.2.x, for example). APIs are deprecated as a suggestion to upgrade to a new, improved API. Updating your project is not required in these cases since the existing API will continue to be supported. The next major version may remove that deprecated API, provided sufficient time has elapsed since the deprecation.
The getEndpoint() function was deprecated just over a year ago because we introduced a suite of endpoint-related helpers (getRepositoryEndpoint(), getGraphQLEndpoint(), getRepositoryName(), isRepositoryEndpoint(), and isRepositoryName()).
getEndpoint() was renamed to getRepositoryEndpoint() to align with the new helpers. getEndpoint() was not removed, however, and can continue to be used. If you are using a code editor that supports inline documentation, like VS Code, you’ll see a deprecation message where the function is used with instructions on how to update your project:
@deprecated Renamed to getRepositoryEndpoint.
Speaking more generally, we take all of our users into consideration when updating our SDKs: both existing and new users.
We want to keep Prismic performant and easy to build with for our existing users. We want to bring you great features that make development easier and make your sites more performant.
We also want it to be easy to learn for our new users. Because of that, we are going to continue to improve our SDKs where necessary while providing as much notice and ease to our existing user base as we can.
We will be releasing @prismicio/client version 7.0.0 in the coming months, where we will remove getEndpoint().
So, in this case, yes we are introducing a breaking change to our JavaScript API, but we have given over a year of notice.
We also added an improvement: You no longer need to pass the endpoint to the client. You can just pass the repository name.
const client = prismic.createClient(repoName);
Thanks for pointing out the error in the docs! We’re going to update that because you brought it to our attention. I’m also looking into ways to make the migration guides easier to find or clearer so that users don’t have a tough time upgrading to the next major version or so that they know what breaking changes are included.
I get how breaking changes are frustrating, and we’ll continue to be conservative with the breaking changes we create. Please let me know if there’s anything I can help with or answer for you.