Clarify the semantics of codelists update

[Jongmassey]

What opensafely codelists update does do:

• downloads the csv version of any codelists ¹ that are listed in codelists.txt that aren't present in codelists.json and adds an entry for them to codelists.json
• checks the SHA of any previously-downloaded codelists in codelists.json against what the OpenCodelists API says the SHA is, and downloads csv and updates codelists.json for those that are different ²
• deletes any files in the codelists/ directory that aren't listed in codelists.json ³

What opensafely codelists update doesn't do:

• update your codelists to the latest version

Many of our users are accustomed to this behaviour, but I feel like we should find out what would be most useful or intuitive to users; including assessing any side-effects of updating codelists.

Footnotes

1. a CodelistVersion in terms of OpenCodelists' models, since the bits of the URL specified in codelists.txt includes a version identifier. What a "codelist" means is different contexts isn't always clear ↩

2. Once a codelist version is "published" or "in review" on OpenCodelists it cannot be definitionally changed, and is pinned to a release of the coding system; EXCEPT for the case of updated VMP IDs in dm+d (see codelist rot) where the downloadable csv version of the codelist contains the latest updated VMP codes which thus changes the SHA ↩

3. commonly-encountered footgun encountered by users using non-opencodelists codelists. The use of the local_codelists directory is documented but still feels surprising to many. ↩