<div dir="ltr"><br><div class="gmail_extra"><div class="gmail_quote">On Sat, Jun 18, 2016 at 4:40 PM, Ben Woods <span dir="ltr"><<a href="mailto:woodsb02@gmail.com" target="_blank">woodsb02@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><span class="">On 18 June 2016 at 17:23, salsaman <span dir="ltr"><<a href="mailto:salsaman@gmail.com" target="_blank">salsaman@gmail.com</a>></span> wrote:<br></span><div class="gmail_extra"><div class="gmail_quote"><span class=""><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div><div><div>Creating a migration guide is standard practice when changing the major version of a well used library API. <br>Is there really no documentation anywhere ? That seems to defeat the purpose of providing a usable library.<br><br></div>Code examples only provide solutions for specific implementation details.<br><br><br></div>Regards,<br></div>Salsaman.<br></div></blockquote><div><br></div></span><div>I second that. FreeBSD is still going through the motions of trying to update numerous open source software packages to use the newest API. And there are plenty which have not yet done it themselves, and therefore require manual patching. We use patches from Linux distributions when they are available, but some are not and we work it out from examples.<br><br></div><div>I believe that a good API documentation should not just explain what is available in each version, but what has changed since the last version and the recommended alternative.<br><br></div><div>Regards,<br></div><div>Ben <br></div></div></div></div>
<br></blockquote><div><br><br></div><div>For reference, here is an example of what I consider to be good migration documentation:<br><br><br></div><div><a href="https://developer.gnome.org/gtk3/stable/gtk-migrating-2-to-3.html">https://developer.gnome.org/gtk3/stable/gtk-migrating-2-to-3.html</a><br><br><br><br></div><div>Gabriel.<br><br></div><div><br clear="all"><br><a href="http://lives-video.com" target="_blank">http://lives-video.com</a><br><a href="https://www.openhub.net/accounts/salsaman" target="_blank">https://www.openhub.net/accounts/salsaman</a><br><br><br><br><br></div></div></div></div>