[Heads up] PR adding guidelines for breaking changes on the website

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

[Heads up] PR adding guidelines for breaking changes on the website

Boost - Dev mailing list
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

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: [Heads up] PR adding guidelines for breaking changes on the website

Boost - Dev mailing list
On 9 February 2018 at 21:32, Louis Dionne via Boost
<[hidden email]> 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

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: [Heads up] PR adding guidelines for breaking changes on the website

Boost - Dev mailing list
On 2/9/2018 7:07 PM, Daniel James via Boost wrote:

> On 9 February 2018 at 21:32, Louis Dionne via Boost
> <[hidden email]> 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."


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: [Heads up] PR adding guidelines for breaking changes on the website

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
On February 9, 2018 7:07:29 PM EST, Daniel James via Boost <[hidden email]> wrote:

> On 9 February 2018 at 21:32, Louis Dionne via Boost
> <[hidden email]> 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

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.)

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost