[racket-dev] help wanted: watch out for missing `@history[...]`

From: Matthew Flatt (mflatt at cs.utah.edu)
Date: Mon Jun 30 05:25:01 EDT 2014

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).


Posted on the dev mailing list.