Updating MIxS standards DRAFT - GenomicsStandardsConsortium/mixs GitHub Wiki
THIS DOCUMENT IS CURRENTLY UNDER REVISION
- this notice will be replaced with a "last modified date" when the working group have finalised the document.
Updating MIxS standards
A major release should be made no more than once per year, ideally targeted for release just prior to the annual meeting. Minor releases can occur at any time when required.
The difference between _major _and _minor _releases is that NCBI/EBI will only ingest major releases, so every major release must include all minor releases since the last major release.
Every major and minor release should be accompanied by a Change-Log listing all updated items including;
- New checklists
- New packages
- New terms
- Deprecated terms
- updated term definitions
- updated term names
- updated term value syntax
- updated term units.
Every major release should include the creation of an archival copy of the previous release in the GitHub repository.
Every major release should be communicated directly to our significant-users group (INSDC, NMDC any others?)
Every major and minor release should include the update to the Source of Truth (SoT) file. Every major and minor release should include the MIxS checklists and packages being made available in the usual variety of formats, including; Excel, LinkML (Sot), JSON and CSV Every major and minor release should include an update to the gensc.org website to ensure the most recent information is included there.
Working with GitHub issues to track updates of MIxS standards:
All works to be incorporated into any MIxS standards should be recorded in the GitHub repository issue tracker with appropriate titles and labels. General discussions will be held at the monthly CIG meetings where brief minutes will be kept in a google doc, but anything directly related to any specific term/package/checklist update should be added to the relevant GitHub issue.
Updates to existing TERMS:
When a term is found to be in need of updating the person making the request should create a GitHub issue ticket here: https://github.com/GenomicsStandardsConsortium/mixs/issues/new/choose using the "Update Term request" template. The user should provide; the details of the term as it currently exists in the SoT (Source of Truth), the details of what they think it should be changed too (if they have a suggestion), along with a comment as to why they believe the change is required and what challenge the change will address, any other context and comments may also be added. The term update template automatically adds the "TermUpdate" label to the issue, but users may also add the appropriate Checklist or Package label if the term changes are specific to one of those. The CIG will check for and address any new tickets, at the latest, during the next CIG monthly call. If members have time tickets may be addressed between calls with any edits/changes being confirmed with the group at the next call. A CIG member will make a branch of the repo (which contains the Schemasheets TSV files); make the relevant update in the TSV file; then make a pull request including notes on the updates made.
Updates to existing PACKAGES:
It is not envisaged that major changes to packages will be a regular occurrence, but if it should happen it will be addressed on a case-by-case basis using a procedure similar to the creation of new packages. It is more likely that updates to individual terms may cause minor changes to packages, e.g. if a term name is changed then the packages that it is used in will also be updated with that term name change. These changes should be made in conjunction with term updates and where possible involve the group(s) responsible for the package(s) affected.
Updates to existing CHECKLISTS:
It is not envisaged that major changes to checklists will be a regular occurrence, but if it should happen it will be addressed on a case by case basis using a procedure similar to the creation of new packages. It is more likely that updates to individual terms may cause minor changes to checklists, e.g. if a term name is changed then the checklists that it is used in will also be updated with that term name change. These changes should be made in conjunction with term updates and where appropriate be signed off by the GenSC board.
Creation of new TERMS:
Creation of new PACKAGES:
When a new package is being suggested it should be presented to the CIG working group at one of the monthly meetings, if its agreed that it could be a MIxS package then we create a GitHub Project for it within the MIXS repository. Tickets are added to the project for all new terms (see the creation of new terms above) as well as 1 ticket to describe the full list of terms that are to be a part of the package (both new and existing terms), this ticket is maintained in the project being updated as changes are made until the package is ready for release either as a minor release or part of a major release. When the package is released the project may be closed.