CHANGES file

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

CHANGES file

Bryan Drewery-6
In ports we have an UPDATING file that is targeted at users and a
CHANGES file that is targeted at developers regarding API changes.

I would like to introduce a CHANGES file as it makes it simpler for
developers to see what has changed without reading through all commit
logs.  This is of great benefit for module writers and vendors who may
even have customized some of the code in the tree.

Some examples of recent changes that are otherwise undocumented:

1. r295707 which introduced g_reset_bio() which *currently* is a wrapper
around bzero, but may change.  At Isilon we had >1 lines of our own code
affected by this change and I feel lucky I noticed it rather than
leaving it to someone to discover years from now when it matters.
2. A lot of my recent share/mk changes may cause grief for vendors (but
not likely out-of-tree builds).
3. callout_stop(9) return value.

Note I am not requesting every little KPI change be documented in here.
 I am only wanting to document ones where a change will break something
for someone and no warning or error is given if they do nothing.  Many
API changes will cause a build error or warning while many do not as
they are not expressible in C or not utilized by our style or captured
by all compilers (like which return values are possible via enum).

Unless someone objects for good reason I will create this file and
encourage others to document their subtle changes in it.  Of course it
will not be 100% but it should be helpful nonetheless.

--
Regards,
Bryan Drewery


signature.asc (484 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: CHANGES file

Mark Johnston-2
On Fri, Mar 11, 2016 at 09:37:43AM -0800, Bryan Drewery wrote:
> In ports we have an UPDATING file that is targeted at users and a
> CHANGES file that is targeted at developers regarding API changes.
>
> I would like to introduce a CHANGES file as it makes it simpler for
> developers to see what has changed without reading through all commit
> logs.  This is of great benefit for module writers and vendors who may
> even have customized some of the code in the tree.

+1

>
> Some examples of recent changes that are otherwise undocumented:
>
> 1. r295707 which introduced g_reset_bio() which *currently* is a wrapper
> around bzero, but may change.  At Isilon we had >1 lines of our own code
> affected by this change and I feel lucky I noticed it rather than
> leaving it to someone to discover years from now when it matters.
> 2. A lot of my recent share/mk changes may cause grief for vendors (but
> not likely out-of-tree builds).
> 3. callout_stop(9) return value.

Some other recent examples:

- DIOGDINFO removal
- a proc_set_cred() call is now needed to set the p_ucred field of a
  process
- callout_drain() return value
- with INVARIANTS, default use of the "trash" destructor in UMA zones
_______________________________________________
[hidden email] mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-arch
To unsubscribe, send any mail to "[hidden email]"
Reply | Threaded
Open this post in threaded view
|

Re: CHANGES file

Ed Maste-2
In reply to this post by Bryan Drewery-6
On 11 March 2016 at 12:37, Bryan Drewery <[hidden email]> wrote:
> In ports we have an UPDATING file that is targeted at users and a
> CHANGES file that is targeted at developers regarding API changes.
>
> I would like to introduce a CHANGES file as it makes it simpler for
> developers to see what has changed without reading through all commit
> logs.  This is of great benefit for module writers and vendors who may
> even have customized some of the code in the tree.

Seems like a good idea to me.

I worry that it will be forgotten on a number of changes, but that's
no worse than today and can be remedied after the fact when a missing
entry is noticed.
_______________________________________________
[hidden email] mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-arch
To unsubscribe, send any mail to "[hidden email]"