opensafely-core / opensafely-core/opensafely-cli

Clarify the semantics of `codelists update`

Open
#298 0 comments 0 reactions 0 assignees View on GitHub

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.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 [^2]
  • deletes any files in the codelists/ directory that aren't listed in codelists.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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.