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

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

Project deadlines

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! 🎉

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.

colebrookson / manuscript