opensafely-core / opensafely-core/opensafely-cli
Clarify the semantics of `codelists update`
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 2
- Forks
- 5
- Avg merge
- 2d 1h
- Merged PRs (30d)
- 4
Description
What opensafely codelists update does do:
- downloads the csv version of any codelists [^1] that are listed in
codelists.txtthat aren't present incodelists.jsonand adds an entry for them tocodelists.json - checks the SHA of any previously-downloaded codelists in
codelists.jsonagainst what the OpenCodelists API says the SHA is, and downloads csv and updatescodelists.jsonfor those that are different [^2] - deletes any files in the
codelists/directory that aren't listed incodelists.json[^3]
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.
[^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.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the opensafely codelists update behavior described for codelists.txt, codelists.json, and the codelists/ directory, then review the linked documentation for local_codelists. Compare the current download, SHA-checking, and deletion semantics with user expectations and side effects. Done means an agreed behavior for latest-version updates and local codelists, with the resulting semantics documented.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- cli, documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100