-
Notifications
You must be signed in to change notification settings - Fork 5
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #8 from MetabolicAtlas/develop
0.4
- Loading branch information
Showing
4 changed files
with
86 additions
and
81 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,110 +1,109 @@ | ||
| standard-GEM v0.3 | ||
| standard-GEM v0.4 | ||
| ================= | ||
|
|
||
| For details about the [aims](https://github.com/SysBioChalmers/standard-GEM/wiki/Aims,-scope-and-terminology#aims), [scope](https://github.com/SysBioChalmers/standard-GEM/wiki/Aims,-scope-and-terminology#scope), and [use case](https://github.com/SysBioChalmers/standard-GEM/wiki/Use-case) of this standard see the [wiki pages of the `standard-GEM` repository](https://github.com/SysBioChalmers/standard-GEM/wiki). | ||
| 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 from the wiki](https://github.com/SysBioChalmers/standard-GEM/wiki/Aims,-scope-and-terminology#terminology) are copied below to facilitate understading of this checklist. | ||
| To facilitate understading, the definitions used throughout this guide are copied below [from the wiki](https://github.com/MetabolicAtlas/standard-GEM/wiki/Aims,-scope-and-terminology#terminology). For easier differentiation, we have associated colors to each of them. | ||
| ``` | ||
| Based on the ISO guidelines, tweaked for easy understanding. | ||
| Requirements: must, must not | ||
| Recommendations: should, should not | ||
| Possibility and capability: can, cannot | ||
| 🟥 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. | ||
| All GEMs that follow the `standard-GEM` must contain this file. This serves as a traceable adherence to the standard. This file must be edited only with [checkmarks](https://help.github.com/en/github/managing-your-work-on-github/about-task-lists). With further updates to `standard-GEM`, one should paste over the new version of this file. | ||
|
|
||
| - [ ] 🟥 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), in order to support automatic parsing and validation of this file. Some of the checkmarks are pre-applied based on the contents of the `standard-GEM` template repository. GEM authors have the responsibility of checking that their model repository does follow 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 | ||
| ------------------- | ||
| - [ ] Navigate to [standard-GEM]() and click on the button `Use this template` | ||
| This will copy the contents of the _master_ branch into the new repository. | ||
| - [ ] 🟨 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 _master_ branch into the new repository, which can be either private or public. | ||
|
|
||
| - [ ] Pick a repository name | ||
| - [ ] 🟥 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. The name can be prefixed by an abbreviation, eg `ec` (enzyme constrained), `sec` (with secretory pathways), `mito` (with mitochondrion pathways), `pro` (with protein structures). | ||
| Example: `ecYeast-GEM` | ||
|
|
||
| - [ ] Pick a repository description | ||
| - [ ] 🟥 Pick a repository description | ||
| The description must include the taxonomic classification in full. | ||
| Example: `The consensus GEM for Saccharomyces cerevisiae` | ||
|
|
||
| - [ ] Add a repository URL | ||
| The URL can be the _doi_. | ||
| - [ ] 🟥 Add repository topic | ||
| The topic `standard-GEM` must be added. Other topics like `genome-scale-models`, `systems-biology` can be added. Having this topic on your repository enables automatic finding using the GitHub API, and automatic validation of the standard. | ||
| Topics are not copied from `standard-GEM`, so they need to be added manually. | ||
|
|
||
| - [ ] Add repository tags | ||
| The tag `standard-GEM` must be added. Other tags like `genome-scale-models`, `systems-biology` can be added. | ||
| Tags are not copied from `standard-GEM`, so they need to be added manually. | ||
| - [ ] 🟨 Add a repository URL | ||
| The URL can be the _doi_. | ||
|
|
||
|
|
||
| Repository workflow | ||
| ------------------- | ||
| The GEM repository must have at least two branches: _master_ and _devel_. Commit messages must follow semantic commits adapted for GEMs. | ||
| A pull request to _master_ must be followed by a release, using the tag format `vX.X.X` where X are numbers, according to semantic versioning principles. The last field (“patch”) can also be used to indicate changes to the repository that do not actually change the GEM itself. | ||
| - [ ] 🟥 Git branches | ||
| The GEM repository must have at least two branches: _master_ and _develop_. | ||
|
|
||
| - [ ] 🟥 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 (“patch”) can also be used to indicate changes to the repository that do not actually change the GEM itself. The use of a `v` before the version number (`v1.0`) is [discouraged](https://semver.org/#is-v123-a-semantic-version). | ||
|
|
||
| For reproducibility, based on the `master` branch create a branch for each paper/presentation, following the format reproducibility/[paper] . It is recommended to also create a release from this branch, and refer to this branch and/or release, including in README.md. Having a release from this reproducibility/ branch ensures its backup on Zenodo. | ||
| - [ ] 🟨 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 the empty folder should not be ignored by _git_. | ||
| `.keep` files are used to indicate that the empty folder should not be ignored by _git_ - without it _git_ would simply not want to version empty directories. Once folders are not empty, it is okay to remove these files. | ||
|
|
||
| - [x] `/.gitignore` | ||
| The repository must contain a `/.gitignore` file. This generic [.gitignore](https://git-scm.com/docs/gitignore) was prepared for multiple programming languages, and does not require modification. | ||
| - [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` | ||
| - [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. | ||
|
|
||
| - [ ] `/.github/CONTRIBUTING.md` | ||
| - [ ] 🟥 `/.github/CONTRIBUTING.md` | ||
| This file is provided by the template, 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/master/.github/CONTRIBUTING.md. | ||
|
|
||
| - [ ] `/code/README.md` | ||
| - [ ] 🟥 `/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 organized. | ||
|
|
||
| - [ ] `/data/README.md` | ||
| - [ ] 🟥 `/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. | ||
|
|
||
| - [ ] `/modelFiles` | ||
| The repository must contain `/modelFiles` folder. | ||
| This folder must contain the model files, in multiple formats, according to the guidelines below. As a general guideline, binary formats (`.mat`, `.xlsx`) must not exist on any other branches than _master_. Otherwise, with time, the size of the repository can create difficulties. | ||
| - [ ] 🟥 `/model` | ||
| The repository must contain `/model` folder. | ||
| This folder must contain the model files, in multiple formats, according to the table below. As a general guideline, binary formats (`.mat`, `.xlsx`) must not exist on any other branches than _master_. The main reason for this 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 introducs 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 | _master_ branch | _devel_ and other branches | | ||
| | ----------------- | --------------- | -------------------------- | | ||
| | JSON `.json` | must | can | | ||
| | Matlab `.mat` | should | must not | | ||
| | sbtab `.tsv` | can | can | | ||
| | Text file `.txt` | must | can | | ||
| | Excel `.xlsx` | must | must not | | ||
| | SBML `.xml` | must | can | | ||
| | YAML `.yml` | must | can | | ||
|
|
||
|
|
||
| - [x] `/docs/ ` | ||
| The repository can contain a `/docs/` folder. A default is provided by the `standard-GEM` template. Its purpose is to instruct GitHub Pages to create a webpage from the main `/README.md` in the repository. This webpage serves as a friendly landing page that requires no maintenance, since it will always be in sync with the `/README.md`. | ||
| The configuration of this webpage is specified by the `_config.yml` file, and can be modified to the desire of the repository owners. As specified in this file, the icon at `/docs/icon.png` will be used on this webpage. | ||
| One need to instruct GitHub to create a website by the following steps: | ||
| 1. navigate to the repository settings | ||
| 2. scroll down to the `GitHub Pages` section | ||
| 3. select as `Source` the `master branch /docs folder` | ||
| 4. the website is now available at `http(s)://[organization or user].github.io/[repository name]`, for example `https://sysbiochalmers.github.io/yeast-GEM/` | ||
|
|
||
| - [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 another license is desired, the file does not require modification. | ||
|
|
||
| - [ ] `/README.md` | ||
| Example: `yeast-GEM.mat` | ||
|
|
||
| | Model file format | _master_ 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. | ||
|
|
||
| - [ ] 🟥 `/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 Zenodo badge. As soon as the first public release is in made, the repository must be archived via Zenodo, and the corresponding badge be updated. A default is provided in the file. | ||
| Additionally, the `/README.md` file should contain [Zenodo](https://zenodo.org) badge. As soon as the first public release is in made, the repository must be archived via Zenodo, and the corresponding badge be updated. A default is provided in the file. | ||
| The `/README.md` can contain a contact badge, for example [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 updates of the repository in the chat room. A default for this badge is provided in the file. | ||
|
|
||
| - [x] `/version.txt` | ||
| - [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 version of the GEM, not of the `standard-GEM`. The value must be updated with each release. | ||
|
|
||
| - [ ] Files for continuous integration testing | ||
| - [ ] 🟨 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`), GitHub Actions (under `.github/workflows`). | ||
|
|
||
| - [ ] _memote_ report | ||
| The repository should contain a _memote_ report on the _master_ branch, in `.html` format. | ||
| - [ ] 🟨 _MEMOTE_ report | ||
| The repository could contain a [MEMOTE](https://www.nature.com/articles/s41587-020-0446-y) report on the _master_ branch, in `.html` format. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
File renamed without changes.