Bryan Drewery
2016-03-11 17:37:43 UTC
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.
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
Regards,
Bryan Drewery