Not just for programmers: How GitHub can accelerate collaborative and reproducible research in ecology and evolution

If you use the code in this repository in a publication, please cite the published paper:

"Braga, P. H. P., Hébert, K., Hudgins, E. J., Scott, E. R., Edwards, B. P. M., Sánchez Reyes, L. L., Grainger, M. J., Foroughirad, V., Hillemann, F., Binley, A. D., Brookson, C. B., Gaynor, K. M., Shafiei Sabet, S., Güncan, A., Weierbach, H., Gomes, D. G. E., & Crystal-Ornelas, R. (2023). Not just for programmers: How GitHub can accelerate collaborative and reproducible research in ecology and evolution. Methods in Ecology and Evolution, 00, 1– 17. https://doi.org/10.1111/2041-210X.14108"

BibTeX entry:

@article{bragaNotJustProgrammers2023,
  title = {Not Just for Programmers: {{How GitHub}} Can Accelerate Collaborative and Reproducible Research in Ecology and Evolution},
  author = {Braga, Pedro Henrique Pereira and H{\'e}bert, Katherine and Hudgins, Emma J. and Scott, Eric R. and Edwards, Brandon P. M. and S{\'a}nchez Reyes, Luna L. and Grainger, Matthew J. and Foroughirad, Vivienne and Hillemann, Friederike and Binley, Allison D. and Brookson, Cole B. and Gaynor, Kaitlyn M. and Shafiei Sabet, Saeed and G{\"u}ncan, Ali and Weierbach, Helen and Gomes, Dylan G. E. and {Crystal-Ornelas}, Robert},
  year = {2023},
  journal = {Methods in Ecology and Evolution},
  volume = {n/a},
  number = {n/a},
  pages = {1-17},
  doi = {10.1111/2041-210X.14108},
  copyright = {All rights reserved},
  langid = {english},
  keywords = {collaboration,data management,ecoinformatics,GitHub,open science,project management,reproducible research,version control},
}

Subject: The use of Github in Ecology and Evolution

Manuscript description

A friendly guide to GitHub and all the things you can currently do with it. Very few papers focus on GitHub as a tool for collaboration. We will also mention where GitHub falls short as a tool for collaboration.

Important links and dates

In this section you'll find a few important links to help us keep track of documents we use outside of the GitHub ecosystem. This includes a google slide deck where we are working on figures, the original outline we made for the manuscript in HackMD, as well as meeting notes.

Links Figure brainstorming

• Figures for manuscript
• Manuscript outline on HackMD
• Meeting notes from:
  • February 2022
  • Jan 2022 (including sign-up sheet for manuscript and figures)
  • Dec 2021
  • Oct 2021
  • Aug 2021

Project deadlines and dates

• March 16, 2022: figures and tables complete
• March 30, 2022: everyone does read through for general edits
• April 13, 2022: Several authors do final detailed read through
• April 27, 2022: Everyone approved before submission
• June 1, 2022: Submit! 🎉
• August 11, 2022: Submitted to Nature Ecology and Evolution;
• August 22, 2022: Declined;
• October 27, 2022: Submitted to Methods in Ecology and Evolution;
• November 17, 2022: Returned for Major Revisions;
• March 5, 2023: Last date for coauthor approval of the revision, response letter, authorship order, and author contributions;
• March 9, 2023: Deadline for the submission of the revision!
• March 10, 2023: Revised version submitted to Methods in Ecology and Evolution!
• March 10, 2023: Accepted for publication in Methods in Ecology and Evolution!!! 🎉

Contributing

A free, personal Github Account is necessary to contribute to this project.

To contribute in writing, you must follow the guidelines described within the CONTRIBUTING.md file.

In a nutshell, suggestions about the literature require the creation of discussions, and written contributions require the modification of files within the content directory and pushing changes through pull requests.

Authorship Guidelines

Authorship contributions are categorized following the guidelines from the CRediT Taxonomy and the International Committee of Medical Journal Editors.

All prospective authors must follow the contributing guidelines within the CONTRIBUTING.md file. There you will find out that you are encouraged to write a few words about yourself in the Self-Introductions discussion section, and you will also see how to fill-in your author information once you contribute to this project.

Repository directories & files

The directories and main files are as follows:

• / (main root) this directory contains this document README.md, which helps uses with the general information about this repository and our project.
• CONTRIBUTING.md contains procedures and directions for prospective authors to contribute to this manuscript.
• USAGE.md contains a getting started with Git guidelines, information on formatting text, citing references, adding figures and tables, and other manuscript editing.
• content contains the manuscript source, which includes markdown files as well as inputs for citations and references and figures.
• R contains R scripts and RMarkdown documents used to generate some of the figures and tables.
• data contains .csv files with raw data used in generating some figures and tables.
• output (and the output and gh-pages branches) contains the outputs (generated files) from Manubot including the resulting manuscript files (in HTML, PDF, and other formats). You should not edit these files manually, because they will be overwritten by the Manubot.
• webpage is a directory meant to be rendered as a static webpage for viewing the HTML manuscript.
• build contains commands and tools for building the manuscript.
• ci contains files necessary for deployment via continuous integration.
• LICENSE.md and LICENSE-CC0.md contain the licenses associated with Manubot and with the content we are developing in this project. Please see the "License" section below.

Continuous Integration

Whenever a pull request is opened, CI (continuous integration) will test whether the changes break the build process to generate a formatted manuscript. The build process aims to detect common errors, such as invalid citations. If your pull request build fails, see the CI logs for the cause of failure and revise your pull request accordingly.

When a commit to the main branch occurs (for example, when a pull request is merged), CI builds the manuscript and writes the results to the gh-pages and output branches. The gh-pages branch uses GitHub Pages to host the following URLs:

• HTML manuscript at https://sortee-github-hackathon.github.io/manuscript/v/latest/index.html
• PDF manuscript at https://sortee-github-hackathon.github.io/manuscript/v/latest/manuscript.pdf

For continuous integration configuration details, see .github/workflows/manubot.yaml.

NOTE: Currently the CI build process does not run and render R Markdown documents. For full reproducibility, files in /R/ need to be 'knit' manually to generate some files needed to build the complete manuscript.

License

Except when noted otherwise, the entirety of this repository is licensed under a CC BY 4.0 License (LICENSE.md), which allows reuse with attribution. Please attribute by linking to https://github.com/SORTEE-Github-Hackathon/manuscript.

Since CC BY is not ideal for code and data, certain repository components are also released under the CC0 1.0 public domain dedication (LICENSE-CC0.md). All files matched by the following glob patterns are dual licensed under CC BY 4.0 and CC0 1.0:

• *.sh
• *.py
• *.yml / *.yaml
• *.json
• *.bib
• *.tsv
• .gitignore

All other files are only available under CC BY 4.0, including:

• *.md
• *.html
• *.pdf
• *.docx

Please open an issue for any question related to licensing.

About Manubot

Manubot is a system for writing scholarly manuscripts via GitHub. Manubot automates citations and references, versions manuscripts using git, and enables collaborative writing via GitHub. An overview manuscript presents the benefits of collaborative writing with Manubot and its unique features. The rootstock repository is a general purpose template for creating new Manubot instances, as detailed in SETUP.md. See USAGE.md for documentation how to write a manuscript.

Please open an issue for questions related to Manubot usage, bug reports, or general inquiries.