Skip to content

Latest commit

 

History

History
231 lines (172 loc) · 19.5 KB

CONTRIBUTING.md

File metadata and controls

231 lines (172 loc) · 19.5 KB
Raw

Contributor guidelines

First of all, thank you for contributing to yeast-GEM! Anybody is welcome to contribute, but please abide by the following guidelines.

You can contribute in 2 main ways: by creating issues, and by sending pull requests (PRs) with additions, deletions, corrections, etc. to the model.

Reporting issues in the model

Report an issue at https://github.com/SysBioChalmers/yeast-GEM/issues if you note any of the following:

  • Incorrect annotation for any model component.
  • Missing feature or field you would like the model to have.
  • Bug/weird simulation results.
  • Lacking documentation.
  • Any type of feedback.

If you are unsure about the issue, consider asking first in our Gitter chat room or GitHub Discussion forum.

When creating the issue, please make sure:

  • You tested your code (if any) with all requirements for running the model.
  • You did your analysis in the main branch of the repository.
  • You provide any necessary files/links needed for understanding the issue.
  • You checked that a similar issue does not exist already

Feel free to also comment on any of the open issues. When doing so, please comply with our code of conduct.

Finally, if you like yeast-GEM please remember to 'star' our Github page (click on the star at top right corner), that way we also have an idea of who is using yeast-GEM!

Contributing to the model

Do you want to contribute to the model with some additions or improvements? Consider starting by raising an issue and assign it to yourself to describe what you want to achieve. This way, we reduce the risk of duplicated efforts and you may also get suggestions on how to best proceed, e.g. there may be half-finished work in some branch that you could start with. Also, feel free to browse our open issues and our ongoing projects: Anything tagged with "help wanted" is open to whoever wants to implement it!

Here is how to set up yeast-GEM for local development to contribute smaller features or changes that you can implement yourself:

  1. First of all, make sure that you have all requirements for contributing to yeast-GEM.

  2. Fork the yeast-GEM repository on GitHub (go to https://github.com/SysBioChalmers/yeast-GEM & click on the upper right corner).

  3. Clone your fork locally:

    git clone https://github.com/<your Github name>/yeast-GEM.git

  4. Check out the branch that you want to contribute to. Most likely that will be develop:

    git checkout develop

  5. Create a branch for local development based on the previously checked out branch (see below for details on the branching model and how to name your branch):

    git checkout -b name-of-your-branch

  6. Now you can make your changes locally!

    • Always make your changes in MATLAB and never directly editing the model files. For loading the model use loadYeastModel.m, and for saving the model use saveYeastModel.m. The latter will ensure all 3 versions of the model (.xml, .yml & .txt) get updated in the same way.
    • Curations to the model are consolidated in scripts that can convert a model from one yeast-GEM release (=version) to the next. Therefore, use the /code/modelCuration/TEMPLATEcuration.m file, or contribute directly to an existing v$VERSION.m script, where $VERSION matches the most recent yeast-GEM release. If the most recent release is 8.6.0, there will be a /code/modelCuration/v8_6_0.m script that consolidates curations to be applied to release 8.6.0.
    • See the TEMPLATEcuration.m script with more description on how to use this file. Look at previous curations files (e.g. v8_6_0.m) to get an idea of how this works.
    • As much as possible follow the model conventions:
      • For metabolite and/or reaction names, please avoid any unconventional characters (e.g. Greek letters).
      • For new genes, please use as id the systematic names from SGD.
    • Store generic scripts in the appropriate folder in /code and data (as .tsv files) in the appropriate folder in /data. If a data file is just to apply one round of curation (for instance a table with selected gene associations to be corrected), it should be stored in the appropriate subfolder in /code/modelCuration. If you think no folder is adequate for your script/data, feel free to create your own folder. Note that binary data such as .mat structures or .xls tables cannot be stored in the repo (as they cannot be version-controlled, and they increment too much the size of the repo).
    • When you are done making changes, review locally your changes with git diff or any git client, to make sure you are modifying the model as you intended.

  7. Commit your changes and push your branch to GitHub.

    git add .
git commit -m "Title of your commit"
git push origin name-of-your-branch

    See below for recommendations on how to name your commits. In case of larger updates, you can of course make several commits on a single contribution. However, if you need to do too many commits, consider if your contribution could be instead split into separate branches (making it easier for reviewing later).

  8. Submit a pull request through the GitHub website (https://help.github.com/articles/creating-a-pull-request-from-a-fork/) to the develop branch of the original SysBioChalmers repo (not your fork). We recommend ticking the box "Allow edits from maintainers" if you wish for us to be able to contribute directly to your branch (speeding-up the reviewing process).

Note that steps 3, 4, 5 and 7 can be done, if you prefer, with any git client, such as Github Desktop.

Finally, and for larger features that you want to work on collaboratively, you may consider to first request to join our development team to get write access to the repository so that you can create a branch directly in the main repository (or simply ask the administrator to create a branch for you). Once you have a new branch, you can push your changes directly to the main repository and when finished, submit a pull request from that branch to develop. See below for more details.

Thank you very much for contributing to yeast-GEM!

Branching model

  • develop: Is the branch all pull-requests should be based on.

  • main: Is only touched by the administrator and is the branch with the tested & reviewed model that is released or ready for the next release.

  • gh-pages: Is only touched by the administrator and for maintaining the landing page of yeast-GEM.

  • {chore, doc, feat, fix, refactor, style}/descriptive-name: Any other branch created in the model. If you work on a fix, start the branch name with fix/, if you work on a feature, start the branch name with feat/. Examples: fix/format_reactions or feat/new_algorithms. See below for more details on the possible actions you can use.

Semantic commits

Please use concise descriptive commit messages. Ideally, use semantic commit messages to make it easier to show what you are aiming to do:

action-object: brief description

  • action = {feat, fix, refactor, style, doc, chore, test}
  • object (optional field) = {rxn, rxn.annot, rxn.prop, met, met.annot, met.prop, gene, gene.annot, comp, comp.annot, data}

action refers to what exactly are you doing in the commit, following a standard definition in software development:

  • chore: updating toolbox, data files, etc.
  • doc: updating documentation or explanatory comments in functions.
  • feat: new feature added, e.g. new reaction / metabolite / function / etc.
  • fix: something that was incorrect in the model and now has been corrected.
  • refactor: see code refactoring.
  • style: minor format changes of model, functions or data (spaces, semi-colons, etc., no code change).

object may or may not be used, and refers to the receiver of the action, i.e. what part of the model/data are you modifying:

  • object: Used when adding/removing/modifying the whole object (rxn, met, gene, comp or data).
  • object.annot: Annotation of the object (e.g. KEGG IDs, EC numbers, etc). Applies for rxn, met, gene or comp.
  • object.prop: Any other property of the object (e.g. formulas, charge, stoich coeffs, LB, UB, etc). Applies for rxn or met.

Some examples:

commit commit message
Add new rxns feat-rxn: methanol pathway
Remove a metabolite fix-met: duplicated citrate
Add metabolite formula feat-met.prop: carbohydrate formulas
Fix rxn stoichiometry fix-rxn.prop: complex V stoich coeffs
Update gene IDs fix-gene.annot: update IDs from SWISSPROT
Format name of compartment style-comp.annot: remove uppercases
Split a rxn in 2 refactor-rxn: split isomerase in 2 steps
Add some data feat-data: metabolomics data
Update documentation of function doc: addDBnewRxn.m
Update toolbox chore: update RAVEN version

More examples here. A more detailed explanation or comments is encouraged to be left in the commit description.

Development team guidelines

This section is meant for the development team of yeast-GEM. As a member of the development team, you should comply with all previous contributor guidelines as well. Besides that, please also consider the following guidelines.

Creating pull requests

Changes to the model cannot be directly committed to the main or develop branches (in fact they are protected). Commits are made to side-branches, after which pull requests are made for merging with develop. For this, follow the instructions for contributors, but consider that as members of the development team have write access to the repository, you can create a branch directly in the main repository without needing to fork, for your convenience. This means that you can:

  • Skip step 2 of the contribution process.
  • In step 3 of the contribution process, clone directly the original repo: 
    git clone https://github.com/SysBioChalmers/yeast-GEM.git

Follow all other steps in the same way. Also, when creating your pull request (or after you have created it):

  • Choose 1 or more members of the team (ideally with knowledge on the pull request) as reviewers. Note that the person making the pull request and the reviewer cannot be the same person.
  • Assign appropriate labels.
  • Assign the pull request to one of the available projects, if applicable.

Reviewing pull requests

Every pull request must be approved by at least one reviewer before it can be merged. When reviewing someone else's pull request, keep in mind the following aspects:

  • Compatibility: First of all, make sure that the model is still compatible with the loading/saving wrappers (loadYeastModel.m & saveYeastModel.m) and that no errors appear. Check also that dependencies.txt does not change in any unexpected ways (e.g. an "unknown" toolbox version). Finally, ensure that the SBML fields model metaid, model id and model name never change, as if they change it would create a conflict in the next release.
  • Documentation: Every change should be justified with a reference/link/argument. This can be provided as data in /data, or directly as a comment in the pull request.
  • Reproducibility: If there are any added scripts, make sure that if you run them, the model gets updated from how it was in develop to how it is in the pull request. For this, you may locally switch to the corresponding branch, replace the .xml file with the one from develop before the changes, and run the associated scripts. Remember to stash any undesired changes afterwards.
  • Style: Ensure that the changes to the model are compliant with the model's rxn/met/gene naming conventions (when unsure, take a look at a similar field in the model). Also, make sure that scripts have a compliant style, and datasets are straight-forward to understand.
  • When commenting in the review, please comply with our code of conduct.
  • Avoid vague comments and try to be as explicit as possible (e.g.: "Please include X here" instead of "X could be included here").
  • As much as possible, try to keep the review process in the pull request discussion, and not in separate private emails.

Administrator guidelines

This section is meant for the administrator of this repo. The main duties of the administrator are:

  • To make sure conventions and standards in the model are kept.
  • To keep the repository clean and organized, i.e. avoid redundancy in functions and/or data, and keep coherency in naming of files.
  • To manage package dependencies and regularly update them.
  • To help in the reviewing process of external pull requests by assigning reviewers, labels and projects, if applicable.
  • To keep issues with the proper labels, and to close them once they are fixed in the main branch.
  • In cases of disagreement between contributors, to decide how to resolve the issue.
  • To merge open pull requests into develop regularly (see below).
  • To generate new releases of the model regularly (see below).

Merging contributions

The following points should be considered when merging branches to develop:

  • Make sure the branch gets accepted by at least one developer with writing access.
  • Wait at least a day before merging, to allow other developers to inspect the pull request.
  • As soon as the branch is merged, check if develop is still possible to merge to main (this can be checked here). If conflicts appear (which should rarely happen and only if the .xml file was changed in an unexpected way by a toolbox update), fix the conflict locally as soon as possible in develop and then push it (note, DO NOT pull any other changes from main to develop, just the single file that is creating the conflict).

Managing python dependencies

We use pip-tools for managing dependencies:

  • If a new dependency is needed for users/developers:

    1. Add the dependency to /requirements/requirements.in or /requirements/dev-requirements.in, respectively (note that by default any requirement in requirements.in will also be in dev-requirements.in).
    2. From /requirements, run pip-compile requirements.in and/or pip-compile dev-requirements.in as needed.

  • If dependencies need to be upgraded, from /requirements run:

    pip-compile --upgrade requirements.in
pip-compile --upgrade dev-requirements.in

    Dependencies should be upgraded regularly, but always first tested in separate branches.

Releasing a new version

  • A merge of develop with main invokes a new release.
  • A new release should be made as soon as there is substantial new work in develop (as rule of thumb, after around 3 pull request merges).

yeast-GEM follows semantic versioning, adapted to GEMs:

  • A major release is seldom used and only meant for a new publication. Backwards compatibility should be, ideally, always preserved.
  • A minor release involves a substantial change in the model (several new reactions/metabolites/genes), such as:
    • Addition of genes/reactions/metabolites from a whole genome annotation.
    • Addition of several annotation fields.
    • Inclusion of a major new formalism in the model.
    • Addition of a plurality of pathways.
  • A patch release is the most common one and is done when only few things have changed in the model, or there are only changes that have to do with format, such as:
    • Adding a single new annotation field.
    • Fixing some chemical formulas/charges.
    • Updating toolboxes.
    • Re-organization of data
    • Refactoring of code.

When releasing, please follow these steps:

  1. Make sure all dependencies in develop correspond to the setup from the local computer from which the release will be made. If not, make a single commit in develop updating this with a loadYeastModel/saveYeastModel cycle.

  2. Create a pull request from develop to main, indicating all new features/fixes/etc. and referencing every previous pull request included (examples here). Tip: if any issue gets solved in the release, write in the pull request description "Closes #X", where "X" is the issue number. That way the issue will be automatically closed after merge.

  3. Merge at least a day after (having at least one accepted review).

  4. Switch locally to main, pull changes and update history.md, by putting at the top the same description of the corresponding PR from step 2.

  5. Bump version with increaseVersion.m. NOTE: The function will error if unexpected changes are occurring. If this happens, probably step 1 was done incorrectly. To fix it, commit in develop any necessary changes and make a new pull request.

  6. Commit changes from steps 4 and 5 with the message chore: version X.Y.Z, and push to the remote.

  7. Make the new release at GitHub here, using the proper tag "vX.Y.Z" and with the same description as the corresponding PR from step 2.

  8. Merge locally main into gh-pages and push to update the landing page.

  9. Review the Zenodo release: Every new release from Github (step 7) automatically triggers a new release in Zenodo. However, so far it is not possible to fully customize this release, and some manual curation is needed. This includes:

    • Ensuring the title of the release has the format SysBioChalmers/yeast-GEM: yeast X.Y.Z.
    • Correcting author names to include all commit authors and PR reviewers that contributed to the release.
    • Ensuring the version of the release has the format vX.Y.Z.
    • Setting the language to English.
    • Adding any grant IDs (if applicable).

    Make sure to both save & publish your edits. You will find the new release at the top of all Zenodo releases. Note that it might take some minutes for the Zenodo release to appear after you create the release in Github.

Acknowledgments

These contribution guidelines were written based on the contribution guidelines of opencobra/cobrapy and SysBioChalmers/RAVEN.