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
