Please bring back the API release notes

Changelog
1

Dear Shopify Developer Team,

I am writing to express concern over the discontinuation of detailed API release notes starting with version 2025-04. While the developer changelog provides updates, it lacks the depth and structure that the release notes previously offered, which are crucial for developers to effectively manage and adapt their applications.

Key Differences Between Release Notes and Changelog:

  1. Structured Summary of Breaking Changes:
  • Release Notes: The 2025-01 release notes included a dedicated section outlining breaking changes, such as the change of the adjustmentPercentage field in SellingPlanPercentagePriceAdjustment from Int to Float, and the deprecation of the storefrontCustomerAccessTokenCreate mutation.
  • Changelog: These critical changes are scattered across multiple entries without a consolidated summary, making it challenging to identify and address breaking changes promptly.
  1. Comprehensive Coverage of Changes:
  • Release Notes: Provided a holistic view of all changes in a given API version, including new features, deprecations, and modifications.
  • Changelog: While it lists updates, it does not offer the same level of comprehensive coverage, potentially leading to overlooked changes that could affect application functionality.
  1. Context and Guidance:
  • Release Notes: Offered context and rationale behind changes, aiding developers in understanding the implications and necessary adjustments.
  • Changelog: Often lacks detailed explanations, leaving developers to interpret the significance and impact of changes independently.

Impact on Development Workflow:

The absence of detailed release notes hampers our ability to:

  • Quickly identify and adapt to breaking changes.
  • Understand the full scope of updates in each API version.
  • Make informed decisions during application development and maintenance.

Request:

I kindly urge the Shopify team to reconsider the decision to discontinue detailed API release notes. Their reinstatement would greatly enhance the developer experience by providing structured, comprehensive, and contextual information necessary for efficient application development and maintenance.

Thank you for your attention to this matter.

2 Likes
2

I support the proposal. Shopify has too many technologies and products. A robust changelog is needed, and it is mandatory.

1 Like
3

It was kind of nice, but I don’t find it hard to use the changelog at Recent changes to Shopify’s platform, filtering by API version, breaking changes, etc. It’s less confusing to have the changes in one spot instead of two. As long as you read all the changes, (at least ones with Action required), you won’t miss anything. And you can also subscribe to updates in this forum so every change will be emailed to you.

4

Did you read @Kyle_W requests details at all or is this a bot response.
The changelog is a glossy overview it lacks a level of critical depth, typically only linking to somewhere else in the docs with around ~5% of the time not even being a valid link, and most the rest of the time the referenced doc STILL lacks critical detail.
And that’s when the changelog even bothers to have an entry for a change instead of a silent update.
Causing a lot of bouncing around to gather info for a migration , it’s unnecessary friction by undoing a system that just worked.

1 Like