Recall that we added `@history[...]` to `scribble/manual` so we can
document the addition of new modules, bindings, arguments, command-line
flags, etc.
It's easy to forget to add a note, and we have no good way of checking
that `@history[]` notes have been added where needed. On the plus side,
I think I've been more consistent with `@history[...]` notes than I was
trying to track changes via HISTORY.txt, and there's no question that
putting the information in the documentation makes it more accessible
and useful than putting it in HISTORY.txt or leaving it to the
repository log. Still, I sometimes forget, and others forget too.
Only a handful of us seem to be making API additions lately (at least
for the libraries in the main repository), so a please remember
message here would be of limited use. But since other people on this
list read each commit, I'm hoping that a please report missing notes
plea might improve our collective memory on this topic. At least, I
would appreciate a ping if you notice that I forget.
For example, here are some recent commits that I think should have
included `@history[]`:
c4a58dc4a5 (now fixed)
05760a12f6 (now fixed)
5280395f88 (now fixed)
500745f41b
74831b41cc
f3c8638366 (now fixed)
0a0c62a1e6
d067311cf7
ddb7477494
e8bfd42d36
For contrast, here are some recent good examples where we remembered to
add `@history[]`:
22f90ce8fe
25cf0ea610
There are some gray areas. I would say that bug fixes generally do not
need `@history[...]` notes, although the case could be made for them.
Similarly, I don't know how much it makes sense to document refinements
to types in `typed/...` libraries (and I'll leave that question to the
TR implementers).
_
Racket Developers list:
http://lists.racket-lang.org/dev
