[Heads up] PR adding guidelines for breaking changes on the website
Folks, In early December 2017, there was a thread asking for guidelines regarding breaking changes: [1]. The conclusion reached in that thread seemed to be agreed upon [2] and I suggested making it part of the library guidelines. I have finally submitted a PR [3] to add it to the library _guidelines_ (not _requirements_). Feel free to take a look at the PR and chime in as this concerns everyone. Cheers, Louis [1]: https://lists.boost.org/Archives/boost/2017/12/240071.php [2]: https://lists.boost.org/Archives/boost/2017/12/240108.php [3]: https://github.com/boostorg/website/pull/300
On 9 February 2018 at 21:32, Louis Dionne via Boost <boost@lists.boost.org> wrote:
Folks,
In early December 2017, there was a thread asking for guidelines regarding breaking changes: [1]. The conclusion reached in that thread seemed to be agreed upon [2] and I suggested making it part of the library guidelines. I have finally submitted a PR [3] to add it to the library _guidelines_ (not _requirements_). Feel free to take a look at the PR and chime in as this concerns everyone.
I merged the PR into the beta site, so you can see it there: https://beta.boost.org/development/requirements.html#Backwards_compatibility
On 2/9/2018 7:07 PM, Daniel James via Boost wrote:
On 9 February 2018 at 21:32, Louis Dionne via Boost <boost@lists.boost.org> wrote:
Folks,
In early December 2017, there was a thread asking for guidelines regarding breaking changes: [1]. The conclusion reached in that thread seemed to be agreed upon [2] and I suggested making it part of the library guidelines. I have finally submitted a PR [3] to add it to the library _guidelines_ (not _requirements_). Feel free to take a look at the PR and chime in as this concerns everyone.
I merged the PR into the beta site, so you can see it there:
https://beta.boost.org/development/requirements.html#Backwards_compatibility
"and users should be noticed and given a few releases to move over." should be I believe "and users should be notified and given a few releases to move over."
On February 9, 2018 7:07:29 PM EST, Daniel James via Boost <boost@lists.boost.org> wrote:
Folks,
In early December 2017, there was a thread asking for guidelines regarding breaking changes: [1]. The conclusion reached in that thread seemed to be agreed upon [2] and I suggested making it part of the library guidelines. I have finally submitted a PR [3] to add it to the library _guidelines_ (not _requirements_). Feel free to take a look at the PR and chime in as
On 9 February 2018 at 21:32, Louis Dionne via Boost <boost@lists.boost.org> wrote: this
concerns everyone.
I merged the PR into the beta site, so you can see it there: https://beta.boost.org/development/requirements.html#Backwards_compatibility
Thanks for floating these guidelines. There are seemingly three bullets that apply to large changes and one for small changes, which is a little odd. I realize there are distinctions, but using bullets doesn't work that well. I'd also use active voice and remove the commentary. Here's my take: "To ensure a successful transition from old to new APIs, library authors are encouraged to follow the following guidelines when introducing breaking changes in a library according to the impact of those changes. "Minor breaking changes are the easiest for users to adapt to. Give users notice for several releases before publishing such changes. "Large breaking changes require more care. If there is a migration path from the old API to the new (for example from Boost.Filesystem v2 to v3), introduce the new API in a separate directory and/or namespace. Give users a few releases to make the change, after which you can remove the old API. "For large breaking changes without a migration path (for example, Boost.Spirit v2 to v3), provide the new API in a new directory and namespace, and preserve the old API. Treat removing the old API the same as removing a Boost library, which requires a significant deprecation period. "If the changes are equivalent to a redesign or rewrite of the library, treat them as a new library. A formal review, or at least a mini review, is highly encouraged." -- Rob (Sent from my portable computation device.)
participants (4)
-
Daniel James -
Edward Diener -
Louis Dionne -
Rob Stewart