Skip to content

Version each model description and let implementations cite the version they follow #13

Closed

Description

@mmcky

Model descriptions will change: rarely, but wording gets clarified, and now and then the model or the calibration changes. Each implementation needs to say which version it follows, and a reader of the PDF needs to see the version at a glance. The buffer-stock description from #5 is at version 0.1 (draft). This issue settles the scheme before the first version is tagged.

Agreed scheme

  • MAJOR.MINOR, numbered separately for each model description. A new major version means implementations must re-run, because the model, the calibration or the required results changed. A new minor version is a touch-up, such as clarified wording, a corrected typo or an added note, and leaves the results alone.
  • 0.x is a draft; 1.0 is the working group's release. While a description is at 0.x, every change raises the minor number, and its changelog entry says whether implementations need to re-run. From 1.0, the major number carries that.

Plan

  • One source. version, status (draft or released) and date go in the front matter of models/<model>/model-description.md. The subtitle drops "version 0.1 (draft)".
  • A version box at the top right of the PDF, showing the version, status and date. templates/plain_latex_wide/ already takes template options and loads tcolorbox, so the box is a small template change. The web page from Publish each model description as a web page alongside its PDF #12 shows the same box, which also carries the AI-disclosure and verification indicators from Disclose AI assistance and record human verification #14.
  • A Git tag and GitHub release for each version, such as buffer-stock/v0.1, with the PDF attached. That gives a permanent link to exactly the version an implementation follows.
  • A changelog for each model, models/<model>/CHANGELOG.md. Each entry gives the version, the date, what changed and whether implementations need to re-run.
  • Implementations cite the version in metadata.yml as model_description_version, with model_description linking to the tag. The HARK example already has both fields; its link currently points at main. The site's library table shows the version in each slot, for example "HARK · v0.1".
  • The rules go in a root CONTRIBUTING.md, next to the disclosure rules from Disclose AI assistance and record human verification #14.
  • Optional: a CI check that a pull request editing model-description.md also changes its version or its changelog.

The first tag, buffer-stock/v0.1, should be made once the PDF carries the box, so the first tagged PDF already shows it. This is planned to land together with #12, after #5 merges.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions