chore: add standard-GEM.md

code/modelCuration/README.md

@@ -2,7 +2,7 @@
 
 Scripts for curating different parts of the model.
 
-Curations between each model release are gathered in consolidated curation scripts that are named after the model version that they are curation. E.g. v8_6_0.m includes updates that should be applied to model version 8.6.0 to result in the next model release.
+Curations between each model release are gathered in consolidated curation scripts that are named after the model version that they generate. E.g. v8_6_1.m includes updates that regenerates model version 8.6.1. These scripts can replicate the curation process, but earlier model releases are best downloaded here: https://github.com/SysBioChalmers/yeast-GEM/releases.
 
 TEMPLATEcuration.m is the template script that should be used to generate a new consolidated curation script after a new model has just been released.
 

data/modelCuration/README.md

@@ -2,7 +2,9 @@
 
 Data files used for performing curations to the model.
 
-Organized in folders that indicate to which model version the changes should be applied. E.g. 'v8_6_0' contains data files to curate model version 8.6.0 (but note that it does not specify the version number of the _new_ model).
+Curations between each model release are gathered in consolidated curation scripts that are named after the model version that they generate. E.g. v8_6_1.m includes updates that regenerates model version 8.6.1. These scripts can replicate the curation process, but earlier model releases are best downloaded here: https://github.com/SysBioChalmers/yeast-GEM/releases.
+
+Organized in folders that indicate which model version will be generated when incorporating this data. E.g. 'v8_6_1' contains data files that is used to regenerate model version 8.6.1.
 
 The data files here mainly exist of list with reactions, metabolites etc., and their annotations.
 

standard-GEM.md

@@ -0,0 +1,109 @@
+standard-GEM 0.5
+=================
+
+For details about the [aims](https://github.com/MetabolicAtlas/standard-GEM/wiki/Aims,-scope-and-terminology#aims), [scope](https://github.com/MetabolicAtlas/standard-GEM/wiki/Aims,-scope-and-terminology#scope), and [use case](https://github.com/MetabolicAtlas/standard-GEM/wiki/Use-case) of this standard see the [wiki pages of the `standard-GEM` repository](https://github.com/MetabolicAtlas/standard-GEM/wiki).
+
+### Terminology
+The definitions used throughout this guide are copied below [from the wiki](https://github.com/MetabolicAtlas/standard-GEM/wiki/Aims,-scope-and-terminology#terminology) to facilitate understanding. For easier differentiation, we have associated colours with each of them.
+```
+Based on the ISO guidelines, tweaked for easy understanding.
+🟥 Requirements: must, must not
+🟧 Recommendations: should, should not
+🟨 Possibility and capability: can
+```
+
+### Instructions
+This document serves as a checklist for creating an open source genome-scale metabolic model (GEM) on GitHub.  
+
+- [x] 🟥 All GEMs that follow the `standard-GEM` must contain this file.  
+This serves as a traceable adherence to the standard, manually confirmed by the original authors. This file must be edited only with [checkmarks](https://help.github.com/en/github/managing-your-work-on-github/about-task-lists), to support automatic parsing and validation. Some of the checkmarks are pre-applied based on the contents of the `standard-GEM` template repository. GEM authors are responsible for checking that their model repository  follows the guidelines entirely.  
+With further updates to `standard-GEM`, one should paste over the new version of this file, and see that the changes in the new guidelines are met.
+
+Repository creation
+-------------------
+- [x] 🟨 Navigate to [standard-GEM](https://github.com/MetabolicAtlas/standard-GEM/) and click on the button `Use this template`  
+The `standard-GEM` template can be used to initiate a repository. This will copy the contents of the _main_ branch into the new repository, which can be either private or public.
+
+- [x] 🟥 Pick a repository name  
+The name must be either a common name, KEGG organism, or taxonomy-derived short name, followed by the extension `-GEM` or `-GSMM`. The `-GEM` extension is preferred to ease pronunciation. An abbreviation can prefix the name, eg., `ec` (enzyme constrained), `sec` (with secretory pathways), `mito` (with mitochondrion pathways), `pro` (with protein structures).  
+Example: `ecYeast-GEM`
+
+- [x] 🟥 Pick a repository description  
+The description must include the taxonomic classification in full.  
+Example: `The consensus GEM for Saccharomyces cerevisiae`
+
+- [x] 🟥 Add repository topic  
+The topic `standard-GEM` must be added. Other topics like `genome-scale-models` and `systems-biology` can be added. Labelling the repository with this topic enables automatic finding using the GitHub API, and automatic validation of the standard.  
+Topics are not copied from `standard-GEM`, so they must be added manually.
+
+- [x] 🟨 Add a repository URL  
+The URL can be the link to the publication/pre-print/website where the model is introduced, eg., via an identifier system (doi/EuropePMC/PubMed).
+
+
+Repository workflow
+-------------------
+- [x] 🟥 Git branches  
+The GEM repository must have at least two branches: _main_ and _develop_.
+
+- [x] 🟥 Releases  
+Releases must use the tag format `X.X.X` where X are numbers, according to [semantic versioning principles](https://semver.org/). The last field, called “patch,” can also be used to indicate changes to the repository that do not change the GEM itself. Using a `v` before the version number (`v1.0`) [is discouraged](https://semver.org/#is-v123-a-semantic-version). For more information about releases, see the [documentation on GitHub](https://docs.github.com/en/github/administering-a-repository/managing-releases-in-a-repository).  
+
+- [x] 🟨 Commits  
+Commit messages can follow the style of semantic commits.
+
+
+File tree
+---------
+`/` signifies the root of the repository.  
+`.keep` files are used to indicate that _git_ will not ignore empty folders. Without these, _git_ would simply not want to version empty directories. Once folders are not empty, these files can be removed.
+
+- [x] 🟥 `/.gitignore`  
+The repository must contain a `/.gitignore` file. This generic [.gitignore](https://git-scm.com/docs/gitignore) was prepared for multiple programming languages. While it does not require modification, it can be further adapted to the needs of the repository.
+
+- [x] 🟥 `/.github`  
+The repository must contain a `/.github` folder, in which the contributing guidelines, code of conduct, issue templates and pull request templates must be placed. Defaults are provided and they do not require any modification.
+
+- [x] 🟥 `/.github/CONTRIBUTING.md`  
+The template provides this file, but it is empty. It must be filled in with the adequate contributing guideline instructions; a good example is https://github.com/SysBioChalmers/yeast-GEM/blob/main/.github/CONTRIBUTING.md.
+
+- [x] 🟥 `/code/README.md`  
+The repository must contain a `/code` folder. This folder must contain all the code used in generating the model. It must also include a `README.md` file that describes how the folder is organised.
+
+- [x] 🟥 `/data/README.md`  
+The repository must contain a `/data` folder. This folder contains the data used in generating the model. It must also include a `README.md` file that describes how the folder is organized.
+
+- [x] 🟥 `/model`  
+The repository must contain a`/model` folder.  
+This folder must contain the model files in multiple formats depending on the branch, according to the table below. As a general guideline, binary formats (`.mat`, `.xlsx`) must not exist on any other branches than _main_. The main reason is that binary files cannot be diff´ed, which means changes cannot be compared to previous versions, thus increasing the chance of errors. Moreover, with time, the size of the repository can create difficulties, and we cannot yet recommend storing these files with Git LFS, as it introduces complexity.  
+For more information on the `sbtab` file format, see [sbtab.net](https://sbtab.net).  
+All model files must be named the same as the repository, and with the appropriate extension.  
+Example: `yeast-GEM.mat`
+
+| Model file format | _main_ branch | _develop_ and other branches |
+| ----------------- | --------------- | ---------------------------- |
+| JSON `.json`      | can             ||
+| Matlab `.mat`     | should          | must not                     |
+| sbtab `.tsv`      | can             ||
+| Text file `.txt`  | must            ||
+| Excel `.xlsx`     | must            | must not                     |
+| SBML `.xml`       | must            ||
+| YAML `.yml`       | must            ||
+
+
+- [x] 🟥 `/LICENSE.md`  
+The repository must contain a license file. The default license is [CC-BY 4.0 International](https://creativecommons.org/licenses/by/4.0/). Unless a different license is desired, the file does not require modification.
+
+- [x] 🟥 `/README.md`  
+The repository must contain a `README.md` file. A default file is provided, and the adequate contents must be filled in.  
+The `/README.md` file must include a version badge. A default is provided in the file.  
+Additionally, the `/README.md` file should contain the [Zenodo](https://zenodo.org) badge. As soon as the first public release is in made, the repository [should be archived via Zenodo](https://github.com/MetabolicAtlas/standard-GEM/wiki/FAQ#zenodo), and the corresponding badge be updated. A default is provided in the file.  
+The `/README.md` can contain a contact badge, eg., [Gitter](https://gitter.io). When setting up the Gitter chat room, the GitHub activity should be synced with Gitter in order to see the latest repository updates in the chat room. The default for this badge is provided in the file.
+
+- [x] 🟥 `/version.txt`  
+The repository must contain this file, which is required for the version badge in the `/README.md`. The value refers to the GEM, not of the `standard-GEM`. The value must be updated with each release.
+
+- [x] 🟨 Files for continuous integration testing  
+The repository can be set up for continuous integration testing using memote with, eg., Travis CI (`.travis.yml`), Jenkins (`Jenkinsfile`), and GitHub Actions (under `.github/workflows`).
+
+- [x] 🟨 _MEMOTE_ report  
+The repository could contain a [MEMOTE](https://www.nature.com/articles/s41587-020-0446-y) report on the _main_ branch in `.html` format.