├── .appveyor.yml ├── .github └── workflows │ ├── ai-revision.yaml │ ├── editorial-comm-render-build-deploy.yaml │ └── manubot.yaml ├── .gitignore ├── CITATION.cff ├── CONTRIBUTING.md ├── LICENSE-CC0.md ├── LICENSE.md ├── R ├── Supp_Info_1.Rmd ├── Supp_Info_1.aux ├── Supp_Info_1.pdf ├── comparison_table.Rmd ├── roles_table.Rmd ├── scatterblob.html └── scatterblob.pdf ├── README.md ├── SETUP.md ├── SORTEE-manuscript.Rproj ├── USAGE.md ├── build ├── README.md ├── assets │ ├── custom-dictionary.txt │ └── style.csl ├── autobuild.sh ├── build.sh ├── environment.yml ├── pandoc │ └── defaults │ │ ├── common.yaml │ │ ├── docx.yaml │ │ ├── html.yaml │ │ ├── latex.yaml │ │ └── pdf-weasyprint.yaml ├── plugins │ ├── accordion.html │ ├── analytics.html │ ├── anchors.html │ ├── attributes.html │ ├── core.html │ ├── d3.html │ ├── hypothesis.html │ ├── inline-svg.html │ ├── jump-to-first.html │ ├── lightbox.html │ ├── link-highlight.html │ ├── mathjax.html │ ├── scite.html │ ├── table-of-contents.html │ └── tooltips.html └── themes │ ├── default.docx │ ├── default.html │ └── nih-grant.docx ├── ci ├── .gitignore ├── README.md ├── deploy.sh ├── install-spellcheck.sh └── install.sh ├── content ├── 00.front-matter.md ├── 01.abstract.md ├── 02.introduction.md ├── 03.use-cases-a.md ├── 04.use-cases-b.md ├── 05.use-cases-c.md ├── 06.discussion-a.md ├── 07.conclusion.md ├── 08.statements.md ├── 09.figures-tables.md ├── 10.comparison_table.md ├── 11.roles_table.md ├── 90.back-matter.md ├── images │ ├── Fig1.png │ ├── Fig1.xcf │ ├── Figure1.pdf │ ├── Figure1.png │ ├── github.svg │ ├── mastodon.svg │ ├── orcid.svg │ ├── roles.png │ ├── scatterblob_0.pdf │ ├── scatterblob_0.png │ ├── scatterblob_0.svg │ ├── scatterblob_1-darjeeling.pdf │ ├── scatterblob_1-darjeeling1.png │ ├── scatterblob_1-darjeeling2.pdf │ ├── scatterblob_1-darjeeling2.png │ ├── scatterblob_1-royal2.pdf │ ├── scatterblob_1-royal2.png │ ├── scatterblob_1-viridis-turbo.pdf │ ├── scatterblob_1-viridis-turbo.png │ ├── scatterblob_1-zissou1.pdf │ ├── scatterblob_1-zissou1.png │ ├── scatterblob_1.pdf │ ├── scatterblob_1.png │ ├── scatterblob_1.svg │ └── twitter.svg ├── manual-references.bib ├── manual-references.json └── metadata.yaml ├── data ├── cognitive_load_table.csv ├── collaborator_roles.csv ├── comparison_table_raw.csv └── scatterblob_data_raw.csv ├── editorial-communication ├── .gitignore ├── .quarto │ └── xref │ │ ├── 90dd3357 │ │ └── INDEX ├── _quarto.yml ├── cover-letter-submission.Qmd ├── custom.scss ├── editorial-communication.Rproj ├── response-template.docx ├── response-to-the-reviewers.Qmd ├── response-to-the-reviewers.pdf └── skeleton.bib ├── output └── README.md ├── setup.bash └── webpage ├── README.md ├── images ├── index.html └── manuscript.pdf /.appveyor.yml: -------------------------------------------------------------------------------- 1 | # See https://www.appveyor.com/docs/getting-started-with-appveyor-for-linux/ 2 | # Don't build branches with a PR, since their build will be created with the PR itself. 3 | # Otherwise there would be two builds -- one for the PR and one for the branch. 4 | # If you're having issues with getting your PR to build, make sure there are no merge conflicts. 5 | skip_branch_with_pr: true 6 | 7 | # Enable 'Do not build on "Push" events' in the AppVeyor project settings 8 | # to only build commits from pull requests 9 | branches: 10 | only: 11 | - main 12 | - master 13 | 14 | # Only run AppVeyor on commits that modify at least one of the following files 15 | # Delete these lines to run AppVeyor on all main/master branch commits 16 | only_commits: 17 | files: 18 | - .appveyor.yml 19 | - build/ 20 | - ci/install.sh 21 | - content/ 22 | 23 | image: ubuntu 24 | services: 25 | - docker 26 | 27 | # Set SPELLCHECK to true to enable Pandoc spellchecking 28 | environment: 29 | SPELLCHECK: true 30 | 31 | install: 32 | # Create the message with the triggering commit before install so it is 33 | # available if the build fails 34 | - TRIGGERING_COMMIT=${APPVEYOR_PULL_REQUEST_HEAD_COMMIT:-APPVEYOR_REPO_COMMIT} 35 | - JOB_MESSAGE=" for commit $TRIGGERING_COMMIT " 36 | - source ci/install.sh 37 | 38 | test_script: 39 | - bash build/build.sh 40 | - MANUSCRIPT_FILENAME=manuscript-$APPVEYOR_BUILD_VERSION-${TRIGGERING_COMMIT:0:7} 41 | - cp output/manuscript.html $MANUSCRIPT_FILENAME.html 42 | - cp output/manuscript.pdf $MANUSCRIPT_FILENAME.pdf 43 | - appveyor PushArtifact $MANUSCRIPT_FILENAME.html 44 | - appveyor PushArtifact $MANUSCRIPT_FILENAME.pdf 45 | - | 46 | if [ "${SPELLCHECK:-}" = "true" ]; then 47 | SPELLING_ERRORS_FILENAME=spelling-errors-$APPVEYOR_BUILD_VERSION-${TRIGGERING_COMMIT:0:7}.txt 48 | cp output/spelling-errors.txt $SPELLING_ERRORS_FILENAME 49 | appveyor PushArtifact $SPELLING_ERRORS_FILENAME 50 | SPELLING_ERROR_LOCATIONS_FILENAME=spelling-error-locations-$APPVEYOR_BUILD_VERSION-${TRIGGERING_COMMIT:0:7}.txt 51 | cp output/spelling-error-locations.txt $SPELLING_ERROR_LOCATIONS_FILENAME 52 | appveyor PushArtifact $SPELLING_ERROR_LOCATIONS_FILENAME 53 | fi 54 | 55 | build: off 56 | 57 | cache: 58 | - ci/cache 59 | 60 | on_success: 61 | - echo "Artifacts available from $APPVEYOR_URL/project/$APPVEYOR_ACCOUNT_NAME/$APPVEYOR_PROJECT_SLUG/builds/$APPVEYOR_BUILD_ID/artifacts" 62 | - echo "Updated PDF available from $APPVEYOR_URL/api/buildjobs/$APPVEYOR_JOB_ID/artifacts/$MANUSCRIPT_FILENAME.pdf" 63 | - appveyor AddMessage "$JOB_MESSAGE is now complete." 64 | - | 65 | if [ "${SPELLCHECK:-}" = "true" ]; then 66 | SPELLING_ERROR_COUNT=($(wc -l $SPELLING_ERROR_LOCATIONS_FILENAME)) 67 | appveyor AddMessage "
Found $SPELLING_ERROR_COUNT potential spelling error(s). Preview:$(head -n 100 $SPELLING_ERROR_LOCATIONS_FILENAME)" 68 | appveyor AddMessage "...
" 69 | fi 70 | 71 | on_failure: 72 | - appveyor AddMessage "$JOB_MESSAGE failed." 73 | 74 | # The following lines can be safely deleted, which will disable AppVeyorBot 75 | # notifications in GitHub pull requests 76 | # Notifications use Mustache templates http://mustache.github.io/mustache.5.html 77 | # See https://www.appveyor.com/docs/notifications/#customizing-message-template 78 | # for available variables 79 | notifications: 80 | - provider: GitHubPullRequest 81 | template: "AppVeyor [build {{buildVersion}}]({{buildUrl}}) 82 | {{#jobs}}{{#messages}}{{{message}}}{{/messages}}{{/jobs}} 83 | {{#passed}}The rendered manuscript from this build is temporarily available for download at:\n\n 84 | {{#jobs}}{{#artifacts}}- [`{{fileName}}`]({{permalink}})\n{{/artifacts}}{{/jobs}}{{/passed}}" 85 | -------------------------------------------------------------------------------- /.github/workflows/ai-revision.yaml: -------------------------------------------------------------------------------- 1 | name: ai-revision 2 | on: 3 | workflow_dispatch: 4 | inputs: 5 | branch: 6 | description: 'Branch to revise' 7 | required: true 8 | type: string 9 | default: 'main' 10 | file_names: 11 | description: 'File names to revise' 12 | required: false 13 | type: string 14 | default: '' 15 | model: 16 | description: 'Language model' 17 | required: true 18 | type: string 19 | default: 'text-davinci-003' 20 | branch_name: 21 | description: 'Output branch' 22 | required: true 23 | type: string 24 | default: 'ai-revision-davinci' 25 | 26 | jobs: 27 | ai-revise: 28 | name: AI Revise 29 | runs-on: ubuntu-latest 30 | defaults: 31 | run: 32 | shell: bash --login {0} 33 | steps: 34 | - name: Checkout Repo 35 | uses: actions/checkout@v3 36 | with: 37 | ref: ${{ inputs.branch }} 38 | - name: Install environment 39 | uses: actions/setup-python@v4 40 | with: 41 | python-version: '3.11' 42 | - name: Install Manubot AI revision dependencies 43 | run: | 44 | # install using the same URL used for manubot in build/environment.yml 45 | manubot_line=$(grep "github.com/manubot/manubot" build/environment.yml) 46 | manubot_url=$(echo "$manubot_line" | awk -F"- " '{print $2}') 47 | 48 | pip install ${manubot_url}#egg=manubot[ai-rev] 49 | - name: Revise manuscript 50 | env: 51 | OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} 52 | AI_EDITOR_LANGUAGE_MODEL: ${{ inputs.model }} 53 | AI_EDITOR_FILENAMES_TO_REVISE: ${{ inputs.file_names }} 54 | # More variables can be specified to control the behavior of the model: 55 | # https://github.com/manubot/manubot-ai-editor/blob/main/libs/manubot_ai_editor/env_vars.py 56 | run: manubot ai-revision --content-directory content/ 57 | - name: Create Pull Request 58 | uses: peter-evans/create-pull-request@v4 59 | with: 60 | commit-message: 'revise using AI model\n\nUsing the OpenAI model ${{ inputs.model }}' 61 | title: 'AI-based revision using ${{ inputs.model }}' 62 | author: OpenAI model ${{ inputs.model }} 63 | add-paths: | 64 | content/*.md 65 | branch: ${{ inputs.branch_name }} 66 | draft: true 67 | -------------------------------------------------------------------------------- /.github/workflows/editorial-comm-render-build-deploy.yaml: -------------------------------------------------------------------------------- 1 | name: Rendering Editorial Communication Material 2 | on: 3 | push: 4 | paths: 5 | - editorial-communication/** 6 | - .github/workflows/editorial-comm-render-build-deploy.yaml 7 | pull_request: 8 | paths: 9 | - editorial-communication/** 10 | 11 | jobs: 12 | editorial-communication-rendering: 13 | name: Render the editorial communication material 14 | runs-on: ubuntu-latest 15 | 16 | steps: 17 | - name: 🛎️ Checkout repository 18 | uses: actions/checkout@v2 19 | 20 | - name: Setup Quarto 21 | uses: quarto-dev/quarto-actions/setup@v2 22 | 23 | - name: 🧶 Render 24 | uses: quarto-dev/quarto-actions/render@v2 25 | with: 26 | to: html 27 | path: "editorial-communication" 28 | 29 | - name: 🔺 Upload artifact containing the letter 30 | uses: actions/upload-artifact@v1 31 | with: 32 | name: editorial-communication 33 | path: editorial-communication/ 34 | 35 | 36 | checkout-and-deploy-editorial-communication: 37 | name: Checkout and deploy the editorial communication material within the gh-pages repository 38 | runs-on: ubuntu-latest 39 | needs: editorial-communication-rendering 40 | 41 | steps: 42 | - name: 🛎️ Checkout again 43 | uses: actions/checkout@v2.3.1 # If you're using actions/checkout@v2 you must set persist-credentials to false in most cases for the deployment to work correctly. 44 | with: 45 | persist-credentials: false 46 | 47 | - name: 🔻 Download artifact containing the book 48 | uses: actions/download-artifact@v1 49 | with: 50 | # Artifact name 51 | name: editorial-communication # optional 52 | # Destination path 53 | path: editorial-communication/ # optional 54 | 55 | - name: 💎 Deploy to GitHub Pages 56 | uses: JamesIves/github-pages-deploy-action@4.1.4 57 | with: 58 | token: ${{ secrets.ACCESS_TOKEN }} 59 | branch: gh-pages # The branch the action should deploy to. 60 | folder: editorial-communication/ 61 | target-folder: editorial-communication # The folder the action should deploy 62 | clean: true 63 | 64 | -------------------------------------------------------------------------------- /.github/workflows/manubot.yaml: -------------------------------------------------------------------------------- 1 | name: Manubot 2 | on: 3 | push: 4 | branches: 5 | - main 6 | - master 7 | pull_request: 8 | branches: 9 | - main 10 | - master 11 | # NOTE: scheduled workflows are supported as of 2022-09-27 (example commented below) 12 | # https://github.com/community/community/discussions/12269#discussioncomment-3747667 13 | # scheduled: 14 | # - cron: '40 10 1 * *' # https://crontab.guru/#40_10_1_*_* 15 | workflow_dispatch: 16 | inputs: 17 | BUILD_PDF: 18 | type: boolean 19 | description: generate PDF output 20 | default: true 21 | BUILD_DOCX: 22 | type: boolean 23 | description: generate DOCX output 24 | default: true 25 | BUILD_LATEX: 26 | type: boolean 27 | description: generate LaTeX output 28 | default: false 29 | SPELLCHECK: 30 | type: boolean 31 | description: Check spelling 32 | default: true 33 | MANUBOT_USE_DOCKER: 34 | type: boolean 35 | description: Use Docker to generate PDF 36 | default: true 37 | jobs: 38 | manubot: 39 | name: Manubot 40 | runs-on: ubuntu-latest 41 | permissions: 42 | contents: write 43 | env: 44 | GITHUB_PULL_REQUEST_SHA: ${{ github.event.pull_request.head.sha }} 45 | # Set SPELLCHECK to true/false for whether to check spelling in this action. 46 | # For workflow dispatch jobs, this SPELLCHECK setting will be overridden by the user input. 47 | SPELLCHECK: true 48 | defaults: 49 | run: 50 | shell: bash --login {0} 51 | steps: 52 | - name: Checkout Repository 53 | uses: actions/checkout@v3 54 | with: 55 | # fetch entire commit history to support get_rootstock_commit 56 | fetch-depth: 0 57 | - name: Set Environment Variables (Workflow Dispatch) 58 | if: github.event_name == 'workflow_dispatch' 59 | run: | 60 | echo "BUILD_PDF=${{ github.event.inputs.BUILD_PDF }}" >> $GITHUB_ENV 61 | echo "BUILD_DOCX=${{ github.event.inputs.BUILD_DOCX }}" >> $GITHUB_ENV 62 | echo "BUILD_LATEX=${{ github.event.inputs.BUILD_LATEX }}" >> $GITHUB_ENV 63 | echo "SPELLCHECK=${{ github.event.inputs.SPELLCHECK }}" >> $GITHUB_ENV 64 | echo "MANUBOT_USE_DOCKER=${{ github.event.inputs.MANUBOT_USE_DOCKER }}" >> $GITHUB_ENV 65 | - name: Set Environment Variables 66 | run: | 67 | TRIGGERING_SHA=${GITHUB_PULL_REQUEST_SHA:-$GITHUB_SHA} 68 | echo "TRIGGERING_SHA_7=${TRIGGERING_SHA::7}" >> $GITHUB_ENV 69 | echo "TRIGGERING_SHA: $TRIGGERING_SHA" 70 | DEFAULT_BRANCH=${{ github.event.repository.default_branch }} 71 | echo "DEFAULT_BRANCH=${DEFAULT_BRANCH}" >> $GITHUB_ENV 72 | echo "DEFAULT_BRANCH_REF=refs/heads/$DEFAULT_BRANCH" >> $GITHUB_ENV 73 | echo "DEFAULT_BRANCH=$DEFAULT_BRANCH" 74 | - name: Cache 75 | uses: actions/cache@v3 76 | with: 77 | path: ci/cache 78 | key: ci-cache-${{ github.ref }} 79 | restore-keys: | 80 | ci-cache-${{ env.DEFAULT_BRANCH_REF }} 81 | - name: Install Environment 82 | uses: conda-incubator/setup-miniconda@v2 83 | with: 84 | activate-environment: manubot 85 | environment-file: build/environment.yml 86 | auto-activate-base: false 87 | miniforge-version: 'latest' 88 | - name: Install Spellcheck 89 | if: env.SPELLCHECK == 'true' 90 | run: bash ci/install-spellcheck.sh 91 | - name: Build Manuscript 92 | run: bash build/build.sh 93 | - name: Upload Artifacts 94 | uses: actions/upload-artifact@v3 95 | with: 96 | name: manuscript-${{ github.run_id }}-${{ env.TRIGGERING_SHA_7 }} 97 | path: output 98 | - name: Deploy Manuscript 99 | if: github.ref == env.DEFAULT_BRANCH_REF && github.event_name != 'pull_request' && !github.event.repository.fork 100 | env: 101 | MANUBOT_ACCESS_TOKEN: ${{ secrets.GITHUB_TOKEN }} 102 | MANUBOT_SSH_PRIVATE_KEY: ${{ secrets.MANUBOT_SSH_PRIVATE_KEY }} 103 | CI_BUILD_WEB_URL: https://github.com/${{ github.repository }}/commit/${{ github.sha }}/checks 104 | CI_JOB_WEB_URL: https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }} 105 | run: bash ci/deploy.sh -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Generated manuscript output files 2 | output/* 3 | !output/README.md 4 | 5 | webpage/v 6 | 7 | # When PDF building fails, a temporary symlink named images in the root 8 | # directory is not removed. 9 | /images 10 | 11 | # Manubot cache directory 12 | ci/cache 13 | 14 | # Pandoc filters downloaded during continuous integration setup 15 | build/pandoc/filters/spellcheck.lua 16 | 17 | # Python 18 | __pycache__/ 19 | *.pyc 20 | 21 | # Jupyter Notebook 22 | .ipynb_checkpoints 23 | 24 | # Misc temporary files 25 | *.bak 26 | 27 | # System specific files 28 | 29 | ## Linux 30 | *~ 31 | .Trash-* 32 | 33 | ## macOS 34 | .DS_Store 35 | ._* 36 | .Trashes 37 | 38 | ## Windows 39 | Thumbs.db 40 | [Dd]esktop.ini 41 | 42 | ## Text Editors 43 | .vscode 44 | .Rproj.user 45 | .Rhistory 46 | manuscript.Rproj 47 | 48 | ## Adding editorial communication generated HTML 49 | editorial-communication/**.html 50 | -------------------------------------------------------------------------------- /CITATION.cff: -------------------------------------------------------------------------------- 1 | # ----------------------------------------------------------- 2 | # CITATION file created with {cffr} R package, v0.4.1 3 | # See also: https://docs.ropensci.org/cffr/ 4 | # ----------------------------------------------------------- 5 | 6 | cff-version: 1.2.0 7 | message: "If you use the code in this repository in a publication, please cite the published paper" 8 | type: software 9 | title: "Code repository for 'Not Just for Programmers: How GitHub Can Accelerate Collaborative and Reproducible Research in Ecology and Evolution'" 10 | doi: 10.17605/OSF.IO/BYPFM 11 | authors: 12 | - family-names: Braga 13 | given-names: Pedro Henrique Pereira 14 | - family-names: Hébert 15 | given-names: Katherine 16 | - family-names: Hudgins 17 | given-names: Emma J. 18 | - family-names: Scott 19 | given-names: Eric R. 20 | - family-names: Edwards 21 | given-names: Brandon P. M. 22 | - family-names: Sánchez Reyes 23 | given-names: Luna L. 24 | - family-names: Grainger 25 | given-names: Matthew J. 26 | - family-names: Foroughirad 27 | given-names: Vivienne 28 | - family-names: Hillemann 29 | given-names: Friederike 30 | - family-names: Binley 31 | given-names: Allison D. 32 | - family-names: Brookson 33 | given-names: Cole B. 34 | - family-names: Gaynor 35 | given-names: Kaitlyn M. 36 | - family-names: Shafiei Sabet 37 | given-names: Saeed 38 | - family-names: Güncan 39 | given-names: Ali 40 | - family-names: Weierbach 41 | given-names: Helen 42 | - family-names: Gomes 43 | given-names: Dylan G. E. 44 | - family-names: Crystal-Ornelas 45 | given-names: Robert 46 | 47 | preferred-citation: 48 | type: article 49 | title: 'Not Just for Programmers: How GitHub Can Accelerate Collaborative and Reproducible Research in Ecology and Evolution' 50 | doi: 10.1111/2041-210X.14108 51 | url: https://besjournals.onlinelibrary.wiley.com/doi/abs/10.1111/2041-210X.14108 52 | authors: 53 | - family-names: Braga 54 | given-names: Pedro Henrique Pereira 55 | - family-names: Hébert 56 | given-names: Katherine 57 | - family-names: Hudgins 58 | given-names: Emma J. 59 | - family-names: Scott 60 | given-names: Eric R. 61 | - family-names: Edwards 62 | given-names: Brandon P. M. 63 | - family-names: Sánchez Reyes 64 | given-names: Luna L. 65 | - family-names: Grainger 66 | given-names: Matthew J. 67 | - family-names: Foroughirad 68 | given-names: Vivienne 69 | - family-names: Hillemann 70 | given-names: Friederike 71 | - family-names: Binley 72 | given-names: Allison D. 73 | - family-names: Brookson 74 | given-names: Cole B. 75 | - family-names: Gaynor 76 | given-names: Kaitlyn M. 77 | - family-names: Shafiei Sabet 78 | given-names: Saeed 79 | - family-names: Güncan 80 | given-names: Ali 81 | - family-names: Weierbach 82 | given-names: Helen 83 | - family-names: Gomes 84 | given-names: Dylan G. E. 85 | - family-names: Crystal-Ornelas 86 | given-names: Robert 87 | year: 2023 88 | journal: "Methods in Ecology and Evolution" 89 | keywords: 90 | - collaboration 91 | - data management 92 | - ecoinformatics 93 | - GitHub 94 | - open science 95 | - project management 96 | - reproducible research 97 | - version control 98 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # How to contribute? 2 | 3 | ## Requirements 4 | 5 | 0.1. A free, personal [Github Account](https://github.com/join?source=header-home) is necessary to contribute to this project. 6 | 7 | 0.2. Become familiar with the concepts and functions of repository, issue, issue template, manuscript source, and pull-request. Visit the [Getting started](https://github.com/SORTEE-Github-Hackathon/manuscript/blob/main/USAGE.md#getting-started) section from the [USAGE.md](https://github.com/SORTEE-Github-Hackathon/manuscript/blob/main/USAGE.md) for a brief summary on these main concepts! 8 | 9 | 0.3. Write a few words about yourself in the [Self-Introductions](https://github.com/SORTEE-Github-Hackathon/manuscript/discussions/4) discussion section. *Copy and paste the following chunk and fill in with your information*: 10 | 11 | ``` 12 | *My Name is*: 13 | 14 | *What do I do*: 15 | 16 | *How can I or with what I would like to contribute*: 17 | 18 | *What is the most trepidation that I have*: 19 | ``` 20 | 21 | ## Contributing with writing 22 | 23 | 1. To situate yourself, access the [current document](https://sortee-github-hackathon.github.io/manuscript/v/latest/index.html) and/or its corresponding sections within the [content](https://github.com/SORTEE-Github-Hackathon/manuscript/tree/main/content) directory; 24 | 25 | 2. It is **essential** that you **always keep your version up-to-date** (_i.e._ always *fetch* and *pull* from the origin), so you are certain to not provide changes to a previous version of the manuscript. The easiest ways to being modifying are to: 26 | 1. [Fork this repository](https://github.com/SORTEE-Github-Hackathon/manuscript/) to your Github profile, and [Contribute](https://github.com/SORTEE-Github-Hackathon/manuscript/blob/main/CONTRIBUTING.md) your modifications from there. *Remember to always fetch upstream to keep your repository up-to-date*.; or, 27 | 2. [Clone this repository](https://github.com/SORTEE-Github-Hackathon/manuscript/) to your computer, create and work from your own [branch](https://github.com/SORTEE-Github-Hackathon/manuscript) and push your committed modifications through [pull requests](https://github.com/SORTEE-Github-Hackathon/manuscript/blob/main/USAGE.md#pull-requests). *Always fetch and pull from the origin when you work, so your local copy is updated.* 28 | 29 | 3. Write text and propose changes to a file by making a pull request: 30 | 1. **Write a sentence per line** and create new paragraphs with two returns; 31 | 2. It is *highly* encouraged to commit frequently, so you can finely track and, if necessary, revert changes. 32 | 3. Add relevant descriptive names to commits and pull requests; 33 | 1. Preferred: `Adding a sentence on how the use of Github can help instructors achieve learning objectives`; 34 | 2. Not preferred: `Update 1`, `Modification`, `asdas blabla`. 35 | 4. For further information about `Markdown` formatting, access the [`USAGE.md`](https://github.com/SORTEE-Github-Hackathon/manuscript/blob/main/USAGE.md) document. 36 | 37 | 4. All pull requests must be reviewed before being merged to the `main` repository. You may **assign reviewers** if you would like someone to specifically review your pull requests. See the [Reviewing pull requests](https://github.com/SORTEE-Github-Hackathon/manuscript/blob/main/CONTRIBUTING.md#reviewing-writing) section for more information; 38 | 39 | 5. Would you like to point to something important, make a question or a suggestion? Begin a conversation in the [Discussions](https://github.com/SORTEE-Github-Hackathon/manuscript/discussions); 40 | 41 | 6. Fill in your author information by initiating a pull request on the [`metadata.yaml`](https://github.com/SORTEE-Github-Hackathon/manuscript/blob/main/content/metadata.yaml) file (the authorship order will be decided later). (_For the purposes of this manuscript, authors must accummulate contributions that go beyond reviewing typos over the lifetime of this project._) 42 | - Authorship contributions are categorized following the guidelines from the [CRediT Taxonomy](https://casrai.org/credit/) and the [International Committee of Medical Journal Editors](http://www.icmje.org/recommendations/browse/roles-and-responsibilities/defining-the-role-of-authors-and-contributors.html). 43 | 44 | 45 | 46 | ## Reviewing writing 47 | 48 | All pull requests should be reviewed by, at least, two other contributors. Pull request reviews can be open, so that anyone can review them. However, you may assign specific reviewers to them. 49 | 50 | When reviewing a pull request, one needs to consider: 51 | 52 | 1. Whether the pull request passed all Manubot checks. Green means good. Red means that there are issues that must be solved *before* merging the text to the main manuscript. [See here for more information](https://github.com/SORTEE-Github-Hackathon/manuscript/blob/main/USAGE.md#pull-requests). 53 | 2. Verify if there are newly cited literature? If yes, are they available in the [Relevant Literature](https://github.com/SORTEE-Github-Hackathon/manuscript/discussions/categories/relevant-papers) section? If not, request the author of the pull request to include it there or add it yourself. The instructions to do it are just below, in the [Suggesting a paper](https://github.com/SORTEE-Github-Hackathon/manuscript/blob/main/CONTRIBUTING.md#suggesting-a-paper) section. 54 | 3. To the extent of your expertise, do you think that there are any ambiguities, oversimplifications or subjects that should be clarified? 55 | 4. Will the text be easy for someone from any scientific discipline to understand? 56 | 57 | If you feel that there are issues in the pull request that needs to be broadly discussed, you should write a comment below and write an issue, while tagging the pull request you have made. 58 | 59 | ## Suggesting a paper 60 | 61 | 1. Choose a paper; 62 | 2. Search for its title or its DOI in the [Relevant Papers](https://github.com/SORTEE-Github-Hackathon/manuscript/discussions/categories/relevant-papers) discussion section; 63 | 3. If the paper you would like to suggest has been already suggested, contribute to the discussion by adding your view about the research piece; 64 | 3. If the paper is not already discussed, create a [New Discussion](https://github.com/SORTEE-Github-Hackathon/manuscript/discussions/new?category=relevant-papers) with the paper title as **Title**, and with the following template filled in: 65 | 66 | ``` 67 | 68 | 69 | ### Title: Include the manuscript's title 70 | 71 | Study Link: Include the https:// link that brings us to the page of the manuscript 72 | Citation: `@doi:replace` 73 | 74 | > Citation must follow the [Manubot-style citation](https://github.com/SORTEE-Github-Hackathon/manuscript/blob/main/USAGE.md#citations). Leave it in blank, if unsure. 75 | 76 | Suggested keywords that help identify the relevance of this paper to Ecology and Evolution: 77 | * Keyword 1 (replace me, copy and paste more than three if needed) 78 | * Keyword 2 (replace me, copy and paste more than three if needed) 79 | * Keyword 3 (replace me, copy and paste more than three if needed) 80 | 81 | ### Which areas of expertise are particularly relevant to the paper? 82 | 83 | - [x] ecology and/or evolution; 84 | - [ ] biostatistics; 85 | - [ ] informatics and computational research; 86 | - [ ] open science and reproducibility; 87 | - [ ] other: replace_with_your_suggestion. 88 | 89 | # Summary 90 | 91 | ### Suggested questions to answer about each paper: 92 | - What is the general main finding or takeaway of the paper? 93 | - What did they analyse and how did they do it? 94 | - What does this paper suggest to improve the issue with reproducibility in science? 95 | - Do you have any concerns about methodology or the interpretation of these results beyond this analysis? 96 | 97 | ### Any comments or notes? 98 | ``` 99 | 100 | ## Opening new discussions 101 | 102 | Any type of discussion related to this project is welcome! You can visit the [Discussions](https://github.com/SORTEE-Github-Hackathon/manuscript/discussions) section of this repository and begin from there. 103 | 104 | You can search for topics and even propose new categories! 105 | 106 | We still have not established what should be an [Issue](https://github.com/SORTEE-Github-Hackathon/manuscript/issues) instead of a [Discussion](https://github.com/SORTEE-Github-Hackathon/manuscript/discussions) topic. 107 | 108 | We can consider that issues are tasks that need to be addressed, are *not* permanent, and thus are made to be closed. We should discuss about this (!). 109 | 110 | > Important: _If you would like to provide changes to files that are not related to the `content` directory, please open a descriptive issue and only perform prospective changes through pull requests._ 111 | -------------------------------------------------------------------------------- /LICENSE-CC0.md: -------------------------------------------------------------------------------- 1 | # CC0 1.0 Universal 2 | 3 | ``` 4 | CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED HEREUNDER. 5 | ``` 6 | 7 | ### Statement of Purpose 8 | 9 | The laws of most jurisdictions throughout the world automatically confer exclusive Copyright and Related Rights (defined below) upon the creator and subsequent owner(s) (each and all, an "owner") of an original work of authorship and/or a database (each, a "Work"). 10 | 11 | Certain owners wish to permanently relinquish those rights to a Work for the purpose of contributing to a commons of creative, cultural and scientific works ("Commons") that the public can reliably and without fear of later claims of infringement build upon, modify, incorporate in other works, reuse and redistribute as freely as possible in any form whatsoever and for any purposes, including without limitation commercial purposes. These owners may contribute to the Commons to promote the ideal of a free culture and the further production of creative, cultural and scientific works, or to gain reputation or greater distribution for their Work in part through the use and efforts of others. 12 | 13 | For these and/or other purposes and motivations, and without any expectation of additional consideration or compensation, the person associating CC0 with a Work (the "Affirmer"), to the extent that he or she is an owner of Copyright and Related Rights in the Work, voluntarily elects to apply CC0 to the Work and publicly distribute the Work under its terms, with knowledge of his or her Copyright and Related Rights in the Work and the meaning and intended legal effect of CC0 on those rights. 14 | 15 | 1. __Copyright and Related Rights.__ A Work made available under CC0 may be protected by copyright and related or neighboring rights ("Copyright and Related Rights"). Copyright and Related Rights include, but are not limited to, the following: 16 | 17 | i. the right to reproduce, adapt, distribute, perform, display, communicate, and translate a Work; 18 | 19 | ii. moral rights retained by the original author(s) and/or performer(s); 20 | 21 | iii. publicity and privacy rights pertaining to a person's image or likeness depicted in a Work; 22 | 23 | iv. rights protecting against unfair competition in regards to a Work, subject to the limitations in paragraph 4(a), below; 24 | 25 | v. rights protecting the extraction, dissemination, use and reuse of data in a Work; 26 | 27 | vi. database rights (such as those arising under Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, and under any national implementation thereof, including any amended or successor version of such directive); and 28 | 29 | vii. other similar, equivalent or corresponding rights throughout the world based on applicable law or treaty, and any national implementations thereof. 30 | 31 | 2. __Waiver.__ To the greatest extent permitted by, but not in contravention of, applicable law, Affirmer hereby overtly, fully, permanently, irrevocably and unconditionally waives, abandons, and surrenders all of Affirmer's Copyright and Related Rights and associated claims and causes of action, whether now known or unknown (including existing as well as future claims and causes of action), in the Work (i) in all territories worldwide, (ii) for the maximum duration provided by applicable law or treaty (including future time extensions), (iii) in any current or future medium and for any number of copies, and (iv) for any purpose whatsoever, including without limitation commercial, advertising or promotional purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each member of the public at large and to the detriment of Affirmer's heirs and successors, fully intending that such Waiver shall not be subject to revocation, rescission, cancellation, termination, or any other legal or equitable action to disrupt the quiet enjoyment of the Work by the public as contemplated by Affirmer's express Statement of Purpose. 32 | 33 | 3. __Public License Fallback.__ Should any part of the Waiver for any reason be judged legally invalid or ineffective under applicable law, then the Waiver shall be preserved to the maximum extent permitted taking into account Affirmer's express Statement of Purpose. In addition, to the extent the Waiver is so judged Affirmer hereby grants to each affected person a royalty-free, non transferable, non sublicensable, non exclusive, irrevocable and unconditional license to exercise Affirmer's Copyright and Related Rights in the Work (i) in all territories worldwide, (ii) for the maximum duration provided by applicable law or treaty (including future time extensions), (iii) in any current or future medium and for any number of copies, and (iv) for any purpose whatsoever, including without limitation commercial, advertising or promotional purposes (the "License"). The License shall be deemed effective as of the date CC0 was applied by Affirmer to the Work. Should any part of the License for any reason be judged legally invalid or ineffective under applicable law, such partial invalidity or ineffectiveness shall not invalidate the remainder of the License, and in such case Affirmer hereby affirms that he or she will not (i) exercise any of his or her remaining Copyright and Related Rights in the Work or (ii) assert any associated claims and causes of action with respect to the Work, in either case contrary to Affirmer's express Statement of Purpose. 34 | 35 | 4. __Limitations and Disclaimers.__ 36 | 37 | a. No trademark or patent rights held by Affirmer are waived, abandoned, surrendered, licensed or otherwise affected by this document. 38 | 39 | b. Affirmer offers the Work as-is and makes no representations or warranties of any kind concerning the Work, express, implied, statutory or otherwise, including without limitation warranties of title, merchantability, fitness for a particular purpose, non infringement, or the absence of latent or other defects, accuracy, or the present or absence of errors, whether or not discoverable, all to the greatest extent permissible under applicable law. 40 | 41 | c. Affirmer disclaims responsibility for clearing rights of other persons that may apply to the Work or any use thereof, including without limitation any person's Copyright and Related Rights in the Work. Further, Affirmer disclaims responsibility for obtaining any necessary consents, permissions or other rights required for any use of the Work. 42 | 43 | d. Affirmer understands and acknowledges that Creative Commons is not a party to this document and has no duty or obligation with respect to this CC0 or use of the Work. 44 | -------------------------------------------------------------------------------- /R/Supp_Info_1.aux: -------------------------------------------------------------------------------- 1 | \relax 2 | \providecommand\hyper@newdestlabel[2]{} 3 | \providecommand\HyperFirstAtBeginDocument{\AtBeginDocument} 4 | \HyperFirstAtBeginDocument{\ifx\hyper@anchor\@undefined 5 | \global\let\oldnewlabel\newlabel 6 | \gdef\newlabel#1#2{\newlabelxx{#1}#2} 7 | \gdef\newlabelxx#1#2#3#4#5#6{\oldnewlabel{#1}{{#2}{#3}}} 8 | \AtEndDocument{\ifx\hyper@anchor\@undefined 9 | \let\newlabel\oldnewlabel 10 | \fi} 11 | \fi} 12 | \global\let\hyper@last\relax 13 | \gdef\HyperFirstAtBeginDocument#1{#1} 14 | \providecommand*\HyPL@Entry[1]{} 15 | \gdef \LT@i {\LT@entry 16 | {1}{30.92621pt}\LT@entry 17 | {2}{166.54471pt}} 18 | \HyPL@Entry{0<>} 19 | \@writefile{toc}{\contentsline {subsection}{Study}{1}{section*.1}\protected@file@percent } 20 | \newlabel{study}{{}{1}{Study}{section*.1}{}} 21 | \@writefile{toc}{\contentsline {subsubsection}{Not just for programmers: How GitHub can accelerate collaborative and reproducible research in ecology and evolution}{1}{section*.2}\protected@file@percent } 22 | \newlabel{not-just-for-programmers-how-github-can-accelerate-collaborative-and-reproducible-research-in-ecology-and-evolution}{{}{1}{Not just for programmers: How GitHub can accelerate collaborative and reproducible research in ecology and evolution}{section*.2}{}} 23 | \@writefile{toc}{\contentsline {subsubsection}{Supplementary Information 1}{1}{section*.3}\protected@file@percent } 24 | \newlabel{supplementary-information-1}{{}{1}{Supplementary Information 1}{section*.3}{}} 25 | \@writefile{toc}{\contentsline {subsubsection}{Representing technical difficulty and degree of collaboration in use cases for Github in ecology and evolution}{1}{section*.4}\protected@file@percent } 26 | \newlabel{representing-technical-difficulty-and-degree-of-collaboration-in-use-cases-for-github-in-ecology-and-evolution}{{}{1}{Representing technical difficulty and degree of collaboration in use cases for Github in ecology and evolution}{section*.4}{}} 27 | \@writefile{toc}{\contentsline {subsubsection}{Data collection}{3}{section*.5}\protected@file@percent } 28 | \newlabel{data-collection}{{}{3}{Data collection}{section*.5}{}} 29 | \@writefile{lot}{\contentsline {table}{\numberline {2}{\ignorespaces '\textbf {Table S1.2.} Indices of technical difficulty and degree of collaboration for each GitHub use case. The first column lists the GitHub use cases that were addressed in the main text. Indices were assessed collaboratively following the steps in Appendix S1.1.\relax }}{4}{table.caption.6}\protected@file@percent } 30 | \providecommand*\caption@xref[2]{\@setref\relax\@undefined{#1}} 31 | \newlabel{tab:data}{{2}{4}{'\textbf {Table S1.2.} Indices of technical difficulty and degree of collaboration for each GitHub use case. The first column lists the GitHub use cases that were addressed in the main text. Indices were assessed collaboratively following the steps in Appendix S1.1.\relax }{table.caption.6}{}} 32 | \@writefile{toc}{\contentsline {subsubsection}{Creating Figure 2: A summary of ways GitHub can be used showing technical difficulty and degree of collaboration for each use case.}{4}{section*.7}\protected@file@percent } 33 | \newlabel{creating-figure-2-a-summary-of-ways-github-can-be-used-showing-technical-difficulty-and-degree-of-collaboration-for-each-use-case.}{{}{4}{Creating Figure 2: A summary of ways GitHub can be used showing technical difficulty and degree of collaboration for each use case}{section*.7}{}} 34 | \@writefile{lof}{\contentsline {figure}{\numberline {1}{\ignorespaces A summary of ways GitHub can be used showing technical difficulty and degree of collaboration for each use case.\relax }}{10}{figure.caption.8}\protected@file@percent } 35 | \gdef \@abspage@last{10} 36 | -------------------------------------------------------------------------------- /R/Supp_Info_1.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SORTEE-Github-Hackathon/manuscript/8d5bc4ece59c37b94e74db337e837df52f6ac713/R/Supp_Info_1.pdf -------------------------------------------------------------------------------- /R/comparison_table.Rmd: -------------------------------------------------------------------------------- 1 | --- 2 | knit: (function(input_file, encoding) { 3 | out_dir <- '../content'; 4 | rmarkdown::render(input_file, 5 | encoding=encoding, 6 | output_file=file.path(dirname(input_file), out_dir, '10.comparison_table.md'))}) 7 | output: 8 | md_document: 9 | variant: gfm #forces table to be markdown, not html 10 | --- 11 | 12 | ```{r setup, include=FALSE} 13 | knitr::opts_chunk$set(echo = FALSE, message = FALSE, warning = FALSE) 14 | library(knitr) 15 | library(tidyverse) #data wrangling 16 | library(here) #for reproducible relative file paths 17 | library(flextable) #another possible table formatting package. Can output to html, word, powerpoint, pdf. Supports cell merging 18 | options(knitr.table.format = 'pipe') 19 | ``` 20 | 21 | 22 | 23 | ```{r wrangle, include=FALSE} 24 | comp_tbl <- read_csv(here("data", "comparison_table_raw.csv")) 25 | ``` 26 | 27 | 28 | ```{r compare} 29 | kable(comp_tbl, caption = "A comparison of technologies commonly used for collaborating on research in Ecology and Evolutionary Biology. In the first column, we group platforms for collaboration into broad guilds. The second column lists the platform for collaboration. The remaining columns indicate whether the platform for collaboration includes certain features {#tbl:compare}") 30 | ``` 31 | 32 | 33 | 34 | 35 | -------------------------------------------------------------------------------- /R/roles_table.Rmd: -------------------------------------------------------------------------------- 1 | --- 2 | knit: (function(input_file, encoding) { 3 | out_dir <- '../content'; 4 | rmarkdown::render(input_file, 5 | encoding=encoding, 6 | output_file=file.path(dirname(input_file), out_dir, '10.roles_table.md'))}) 7 | output: 8 | md_document: 9 | variant: gfm #forces table to be markdown, not html 10 | --- 11 | 12 | ```{r setup, include=FALSE} 13 | knitr::opts_chunk$set(echo = FALSE, message = FALSE, warning = FALSE) 14 | library(knitr) 15 | library(tidyverse) #data wrangling 16 | library(here) #for reproducible relative file paths 17 | library(flextable) #another possible table formatting package. Can output to html, word, powerpoint, pdf. Supports cell merging 18 | options(knitr.table.format = 'pipe') 19 | ``` 20 | 21 | 22 | 23 | ```{r wrangle, include=FALSE} 24 | roles <- read_csv(here("data", "collaborator_roles.csv")) 25 | 26 | roles_wide <- 27 | roles %>% 28 | tidyr::fill(Role, Description) %>% 29 | pivot_wider(names_from = `GitHub Feature`, values_from = `Use Case`) %>% 30 | select(Role, `GitHub repository`, README, Issue, Discussion, `Pull Request`, Fork, `GitHub Pages`) %>% 31 | mutate(across(everything(), ~replace_na(.x, ""))) 32 | ``` 33 | 34 | ```{r save-img, include=FALSE} 35 | #produce a png version using flextable() 36 | roles_table <- flextable(roles_wide) %>% 37 | valign(j=1:8, valign = "top") %>% 38 | border_outer() %>% 39 | border_inner_h() %>% 40 | border_inner_v() 41 | # save_as_image(roles_table, here("content", "images", "roles_hires.pdf")) 42 | save_as_image(roles_table, here("content", "images", "roles.png")) 43 | ``` 44 | 45 | ```{r roles} 46 | kable(roles_wide, caption = "A non-exhaustive collection of ideas for how various GitHub features could be utilized for a research project. Here we have categorized contributors/collaborators into five roles. A Project Manager owns the GitHub repository for a project, and leads the academic project (e.g., lead author of a manuscript). A co-author contributes to writing and other aspects of research, but may have limited or no experience with programming, git, and/or GitHub. A code contributor writes or edits analysis code for the project. A code reviewer could be a project collaborator or a peer reviewer who reviews project code. They are familiar with coding, but not necessarily with git or GitHub (but they are willing to learn). Finally, community members could be other researchers or non-researchers interested in reproducing results, re-using code or data, or communicating with researchers involved in the project. These roles are not mutually exclusive—a co-author could also be a code contributor and code reviewer, for example. For definitions of the GitHub features, see Box 1. {#tbl:roles}") 47 | ``` 48 | 49 | 50 | -------------------------------------------------------------------------------- /R/scatterblob.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SORTEE-Github-Hackathon/manuscript/8d5bc4ece59c37b94e74db337e837df52f6ac713/R/scatterblob.pdf -------------------------------------------------------------------------------- /SORTEE-manuscript.Rproj: -------------------------------------------------------------------------------- 1 | Version: 1.0 2 | 3 | RestoreWorkspace: No 4 | SaveWorkspace: No 5 | AlwaysSaveHistory: Default 6 | 7 | EnableCodeIndexing: Yes 8 | UseSpacesForTab: Yes 9 | NumSpacesForTab: 2 10 | Encoding: UTF-8 11 | 12 | RnwWeave: Sweave 13 | LaTeX: pdfLaTeX 14 | -------------------------------------------------------------------------------- /build/README.md: -------------------------------------------------------------------------------- 1 | # Building the manuscript 2 | 3 | [`build.sh`](build.sh) builds the repository. 4 | `bash build/build.sh` should be executed from the root directory of the repository. 5 | By default, `build.sh` creates HTML and PDF outputs. 6 | However, setting the `BUILD_PDF` environment variable to `false` will suppress PDF output. 7 | For example, run local builds using the command `BUILD_PDF=false bash build/build.sh`. 8 | 9 | To build a DOCX file of the manuscript, set the `BUILD_DOCX` environment variable to `true`. 10 | For example, use the command `BUILD_DOCX=true bash build/build.sh`. 11 | To export DOCX for all CI builds, set an environment variable (see docs for [GitHub Actions](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/using-environment-variables)). 12 | Currently, equation numbers via `pandoc-eqnos` are not supported for DOCX output. 13 | 14 | Format conversion is done using [Pandoc](https://pandoc.org/MANUAL.html). 15 | `build.sh` calls `pandoc` commands using the options specified in [`pandoc/defaults`](pandoc/defaults). 16 | Each file specifies a set of pandoc `--defaults` options for a given format. 17 | To change the options, either edit the YAML files directly or add additional `--defaults` files. 18 | 19 | ## Environment 20 | 21 | Note: currently, **Windows is not supported**. 22 | 23 | Install the [conda](https://conda.io) environment specified in [`environment.yml`](environment.yml) by running the following commands 24 | (from the repository's root directory): 25 | 26 | ```sh 27 | # Install the environment 28 | conda env create --file build/environment.yml 29 | ``` 30 | 31 | If the `manubot` environment is already installed, but needs to be updated to reflect changes to `environment.yml`, use one of the following options: 32 | 33 | ```shell 34 | # option 1: update the existing environment. 35 | conda env update --file build/environment.yml 36 | 37 | # option 2: remove and reinstall the manubot environment. 38 | # Slower than option 1, but guarantees a fresh environment. 39 | conda env remove --name manubot 40 | conda env create --file build/environment.yml 41 | ``` 42 | 43 | Activate with `conda activate manubot` (assumes `conda` version of [at least](https://github.com/conda/conda/blob/9d759d8edeb86569c25f6eb82053f09581013a2a/CHANGELOG.md#440-2017-12-20) 4.4). 44 | The environment should successfully install on both Linux and macOS. 45 | However, it will fail on Windows due to the [`pango`](https://anaconda.org/conda-forge/pango) dependency. 46 | 47 | Because the build process is dependent on having the appropriate version of the `manubot` Python package, 48 | it is necessary to use the version specified in `environment.yml`. 49 | The latest `manubot` release on PyPI may not be compatible with the latest version of this rootstock repository. 50 | 51 | ## Building PDFs 52 | 53 | If Docker is available, `build.sh` uses the [Athena](https://www.athenapdf.com/) [Docker image](https://hub.docker.com/r/arachnysdocker/athenapdf) to build the PDF. 54 | Otherwise, `build.sh` uses [WeasyPrint](https://weasyprint.org/) to build the PDF. 55 | It is common for WeasyPrint to generate many warnings and errors that can be safely ignored. 56 | Examples are shown below: 57 | 58 | ```text 59 | WARNING: Ignored `pointer-events: none` at 3:16, unknown property. 60 | WARNING: Ignored `font-display:auto` at 1:53114, descriptor not supported. 61 | ERROR: Failed to load font at "https://use.fontawesome.com/releases/v5.7.2/webfonts/fa-brands-400.eot#iefix" 62 | WARNING: Expected a media type, got only/**/screen 63 | ``` 64 | -------------------------------------------------------------------------------- /build/assets/custom-dictionary.txt: -------------------------------------------------------------------------------- 1 | personal_ws-1.1 en 22 2 | al 3 | doi 4 | eq 5 | et 6 | github 7 | isbn 8 | latex 9 | manubot 10 | orcid 11 | permalink 12 | pmc 13 | pmcid 14 | pmid 15 | pubmed 16 | rootstock 17 | s 18 | strikethrough 19 | svg 20 | svgs 21 | tbl 22 | unicode 23 | wikidata 24 | -------------------------------------------------------------------------------- /build/assets/style.csl: -------------------------------------------------------------------------------- 1 | 2 | 79 | -------------------------------------------------------------------------------- /build/autobuild.sh: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env bash 2 | 3 | ## autobuild.sh: automatically rebuild mansucript outputs and the webpage when content changes 4 | ## Depends on watchdog https://github.com/gorakhargosh/watchdog 5 | 6 | watchmedo shell-command \ 7 | --wait \ 8 | --command='bash build/build.sh && manubot webpage' \ 9 | content 10 | -------------------------------------------------------------------------------- /build/build.sh: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env bash 2 | 3 | ## build.sh: compile manuscript outputs from content using Manubot and Pandoc 4 | 5 | set -o errexit \ 6 | -o nounset \ 7 | -o pipefail 8 | 9 | # Set timezone used by Python for setting the manuscript's date 10 | export TZ=Etc/UTC 11 | # Default Python to read/write text files using UTF-8 encoding 12 | export LC_ALL=en_US.UTF-8 13 | 14 | 15 | # Set DOCKER_RUNNING to true if docker is running, otherwise false. 16 | DOCKER_RUNNING="$(docker info &> /dev/null && echo "true" || (true && echo "false"))" 17 | 18 | # Set option defaults 19 | CI="${CI:-false}" 20 | BUILD_PDF="${BUILD_PDF:-true}" 21 | BUILD_DOCX="${BUILD_DOCX:-true}" 22 | BUILD_LATEX="${BUILD_LATEX:-true}" 23 | SPELLCHECK="${SPELLCHECK:-true}" 24 | MANUBOT_USE_DOCKER="${MANUBOT_USE_DOCKER:-$DOCKER_RUNNING}" 25 | # Pandoc's configuration is specified via files of option defaults 26 | # located in the $PANDOC_DATA_DIR/defaults directory. 27 | PANDOC_DATA_DIR="${PANDOC_DATA_DIR:-build/pandoc}" 28 | 29 | # Generate reference information 30 | echo >&2 "Retrieving and processing reference metadata" 31 | manubot process \ 32 | --content-directory=content \ 33 | --output-directory=output \ 34 | --cache-directory=ci/cache \ 35 | --skip-citations \ 36 | --log-level=INFO 37 | 38 | # Make output directory 39 | mkdir -p output 40 | 41 | # Create HTML output 42 | # https://pandoc.org/MANUAL.html 43 | echo >&2 "Exporting HTML manuscript" 44 | pandoc --verbose \ 45 | --data-dir="$PANDOC_DATA_DIR" \ 46 | --defaults=common.yaml \ 47 | --defaults=html.yaml 48 | 49 | # Create PDF output (unless BUILD_PDF environment variable equals "false") 50 | # If Docker is not available, use WeasyPrint to create PDF 51 | if [ "${BUILD_PDF}" != "false" ] && [ "${MANUBOT_USE_DOCKER}" != "true" ]; then 52 | echo >&2 "Exporting PDF manuscript using WeasyPrint" 53 | if [ -L images ]; then rm images; fi # if images is a symlink, remove it 54 | ln -s content/images 55 | pandoc \ 56 | --data-dir="$PANDOC_DATA_DIR" \ 57 | --defaults=common.yaml \ 58 | --defaults=html.yaml \ 59 | --defaults=pdf-weasyprint.yaml 60 | rm images 61 | fi 62 | 63 | # If Docker is available, use athenapdf to create PDF 64 | if [ "${BUILD_PDF}" != "false" ] && [ "${MANUBOT_USE_DOCKER}" == "true" ]; then 65 | echo >&2 "Exporting PDF manuscript using Docker + Athena" 66 | if [ "${CI}" = "true" ]; then 67 | # Incease --delay for CI builds to ensure the webpage fully renders, even when the CI server is under high load. 68 | # Local builds default to a shorter --delay to minimize runtime, assuming proper rendering is less crucial. 69 | MANUBOT_ATHENAPDF_DELAY="${MANUBOT_ATHENAPDF_DELAY:-5000}" 70 | echo >&2 "Continuous integration build detected. Setting athenapdf --delay=$MANUBOT_ATHENAPDF_DELAY" 71 | fi 72 | if [ -d output/images ]; then rm -rf output/images; fi # if images is a directory, remove it 73 | cp -R -L content/images output/ 74 | docker run \ 75 | --rm \ 76 | --shm-size=1g \ 77 | --volume="$(pwd)/output:/converted/" \ 78 | --security-opt=seccomp:unconfined \ 79 | arachnysdocker/athenapdf:2.16.0 \ 80 | athenapdf \ 81 | --delay=${MANUBOT_ATHENAPDF_DELAY:-1100} \ 82 | --pagesize=A4 \ 83 | manuscript.html manuscript.pdf 84 | rm -rf output/images 85 | fi 86 | 87 | # Create DOCX output (if BUILD_DOCX environment variable equals "true") 88 | if [ "${BUILD_DOCX}" = "true" ]; then 89 | echo >&2 "Exporting Word Docx manuscript" 90 | pandoc --verbose \ 91 | --data-dir="$PANDOC_DATA_DIR" \ 92 | --defaults=common.yaml \ 93 | --defaults=docx.yaml 94 | fi 95 | 96 | # Create LaTeX output (if BUILD_LATEX environment variable equals "true") 97 | if [ "${BUILD_LATEX}" = "true" ]; then 98 | echo >&2 "Exporting LaTeX manuscript" 99 | pandoc \ 100 | --data-dir="$PANDOC_DATA_DIR" \ 101 | --defaults=common.yaml \ 102 | --defaults=latex.yaml 103 | fi 104 | 105 | # Spellcheck 106 | if [ "${SPELLCHECK}" = "true" ]; then 107 | export ASPELL_CONF="add-extra-dicts $(pwd)/build/assets/custom-dictionary.txt; ignore-case true" 108 | 109 | # Identify and store spelling errors 110 | pandoc \ 111 | --data-dir="$PANDOC_DATA_DIR" \ 112 | --lua-filter spellcheck.lua \ 113 | output/manuscript.md \ 114 | | sort -fu > output/spelling-errors.txt 115 | echo >&2 "Potential spelling errors:" 116 | cat output/spelling-errors.txt 117 | 118 | # Add additional forms of punctuation that Pandoc converts so that the 119 | # locations can be detected 120 | # Create a new expanded spelling errors file so that the saved artifact 121 | # contains only the original misspelled words 122 | cp output/spelling-errors.txt output/expanded-spelling-errors.txt 123 | grep "’" output/spelling-errors.txt | sed "s/’/'/g" >> output/expanded-spelling-errors.txt || true 124 | 125 | # Find locations of spelling errors 126 | # Use "|| true" after grep because otherwise this step of the pipeline will 127 | # return exit code 1 if any of the markdown files do not contain a 128 | # misspelled word 129 | cat output/expanded-spelling-errors.txt | while read word; do grep -ion "\<$word\>" content/*.md; done | sort -h -t ":" -k 1b,1 -k2,2 > output/spelling-error-locations.txt || true 130 | echo >&2 "Filenames and line numbers with potential spelling errors:" 131 | cat output/spelling-error-locations.txt 132 | 133 | rm output/expanded-spelling-errors.txt 134 | fi 135 | 136 | echo >&2 "Build complete" 137 | -------------------------------------------------------------------------------- /build/environment.yml: -------------------------------------------------------------------------------- 1 | name: manubot 2 | channels: 3 | - conda-forge 4 | dependencies: 5 | - cairo=1.16.0 6 | - cairocffi=1.2.0 7 | - ghp-import=2.1.0 8 | - jinja2=3.1.2 9 | - jsonschema=4.17.0 10 | - librsvg=2.52.5 11 | - pandoc=2.19.2 12 | - pango=1.48.10 13 | - pip=23.0.1 14 | - python=3.11.0 15 | - requests-cache=0.9.6 16 | - requests=2.28.1 17 | - tomli=2.0.1 18 | - watchdog==2.1.9 19 | - weasyprint=53.4 20 | - yamllint=1.28.0 21 | - pip: 22 | - cffi==1.15.0 23 | - errorhandler==2.0.1 24 | - git+https://github.com/manubot/manubot@f62dd4cfdebf67f99f63c9b2e64edeaa591eeb69 25 | - isbnlib==3.10.10 26 | - opentimestamps-client==0.7.1 27 | - opentimestamps==0.4.3 28 | - pandoc-eqnos==2.5.0 29 | - pandoc-fignos==2.4.0 30 | - pandoc-tablenos==2.3.0 31 | - pandoc-xnos==2.5.0 32 | - pandocfilters==1.5.0 33 | - panflute==2.2.3 34 | - psutil==5.9.4 35 | - pybase62==0.5.0 36 | - python-bitcoinlib==0.11.2 37 | - pyyaml==6.0 38 | -------------------------------------------------------------------------------- /build/pandoc/defaults/common.yaml: -------------------------------------------------------------------------------- 1 | # Pandoc --defaults shared between Manubot output formats. 2 | from: markdown 3 | input-file: output/manuscript.md 4 | filters: 5 | - pandoc-fignos 6 | - pandoc-eqnos 7 | - pandoc-tablenos 8 | - pandoc-manubot-cite 9 | - citeproc 10 | wrap: preserve 11 | metadata: 12 | csl: https://raw.githubusercontent.com/citation-style-language/styles/master/dependent/methods-in-ecology-and-evolution.csl 13 | link-citations: true 14 | -------------------------------------------------------------------------------- /build/pandoc/defaults/docx.yaml: -------------------------------------------------------------------------------- 1 | # Pandoc --defaults for DOCX output. 2 | # Load on top of common defaults. 3 | to: docx 4 | output-file: output/manuscript.docx 5 | reference-doc: build/themes/default.docx 6 | resource-path: 7 | - '.' 8 | - content 9 | -------------------------------------------------------------------------------- /build/pandoc/defaults/html.yaml: -------------------------------------------------------------------------------- 1 | # Pandoc --defaults for HTML output. 2 | # Load on top of common defaults. 3 | to: html5 4 | output-file: output/manuscript.html 5 | # include-before-body: 6 | ### third-party plugins 7 | #- build/plugins/d3.html 8 | include-after-body: 9 | ### theme 10 | - build/themes/default.html 11 | ### first-party plugins 12 | - build/plugins/core.html # needed for all first-party plugins 13 | - build/plugins/accordion.html 14 | - build/plugins/anchors.html 15 | - build/plugins/attributes.html 16 | #- build/plugins/inline-svg.html 17 | - build/plugins/jump-to-first.html 18 | - build/plugins/lightbox.html 19 | - build/plugins/link-highlight.html 20 | - build/plugins/table-of-contents.html 21 | - build/plugins/tooltips.html 22 | ### third-party plugins 23 | - build/plugins/analytics.html 24 | - build/plugins/hypothesis.html 25 | - build/plugins/mathjax.html 26 | #- build/plugins/scite.html 27 | variables: 28 | document-css: false 29 | math: "" 30 | html-math-method: 31 | method: mathjax 32 | -------------------------------------------------------------------------------- /build/pandoc/defaults/latex.yaml: -------------------------------------------------------------------------------- 1 | # Pandoc --defaults for LaTeX output. 2 | # Load on top of common defaults. 3 | to: latex 4 | output-file: output/manuscript.tex 5 | -------------------------------------------------------------------------------- /build/pandoc/defaults/pdf-weasyprint.yaml: -------------------------------------------------------------------------------- 1 | # Pandoc --defaults for PDF output via weasyprint. 2 | # Load on top of HTML defaults. 3 | output-file: output/manuscript.pdf 4 | pdf-engine: weasyprint 5 | pdf-engine-opts: 6 | - '--presentational-hints' 7 | html-math-method: 8 | method: webtex 9 | url: 'https://latex.codecogs.com/svg.latex?' 10 | -------------------------------------------------------------------------------- /build/plugins/accordion.html: -------------------------------------------------------------------------------- 1 | 6 | 7 | 102 | 103 | 104 | 105 | 114 | 115 | 147 | -------------------------------------------------------------------------------- /build/plugins/analytics.html: -------------------------------------------------------------------------------- 1 | 6 | -------------------------------------------------------------------------------- /build/plugins/anchors.html: -------------------------------------------------------------------------------- 1 | 9 | 10 | 76 | 77 | 78 | 79 | 88 | 89 | 129 | -------------------------------------------------------------------------------- /build/plugins/attributes.html: -------------------------------------------------------------------------------- 1 | 8 | 9 | 86 | -------------------------------------------------------------------------------- /build/plugins/core.html: -------------------------------------------------------------------------------- 1 | 6 | 7 | 130 | -------------------------------------------------------------------------------- /build/plugins/d3.html: -------------------------------------------------------------------------------- 1 | 7 | 8 | 13 | -------------------------------------------------------------------------------- /build/plugins/hypothesis.html: -------------------------------------------------------------------------------- 1 | 6 | 7 | 87 | 88 | 89 | 90 | 100 | 101 | 167 | -------------------------------------------------------------------------------- /build/plugins/inline-svg.html: -------------------------------------------------------------------------------- 1 | 15 | 16 | 54 | -------------------------------------------------------------------------------- /build/plugins/jump-to-first.html: -------------------------------------------------------------------------------- 1 | 7 | 8 | 75 | 76 | 77 | 78 | 87 | 88 | 105 | -------------------------------------------------------------------------------- /build/plugins/link-highlight.html: -------------------------------------------------------------------------------- 1 | 9 | 10 | 126 | 127 | 158 | -------------------------------------------------------------------------------- /build/plugins/mathjax.html: -------------------------------------------------------------------------------- 1 | 7 | 8 | 17 | 18 | 23 | 24 | 54 | -------------------------------------------------------------------------------- /build/plugins/scite.html: -------------------------------------------------------------------------------- 1 | 7 | 8 | 13 | 14 | 50 | 51 | 63 | -------------------------------------------------------------------------------- /build/themes/default.docx: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SORTEE-Github-Hackathon/manuscript/8d5bc4ece59c37b94e74db337e837df52f6ac713/build/themes/default.docx -------------------------------------------------------------------------------- /build/themes/nih-grant.docx: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SORTEE-Github-Hackathon/manuscript/8d5bc4ece59c37b94e74db337e837df52f6ac713/build/themes/nih-grant.docx -------------------------------------------------------------------------------- /ci/.gitignore: -------------------------------------------------------------------------------- 1 | # SSH public and private keys 2 | deploy.key* 3 | -------------------------------------------------------------------------------- /ci/README.md: -------------------------------------------------------------------------------- 1 | # Continuous integration tools 2 | 3 | This directory contains tools and files for continuous integration (CI). 4 | Specifically, [`deploy.sh`](deploy.sh) runs on successful `main` branch builds that are not pull requests. 5 | The contents of `../webpage` are committed to the `gh-pages` branch. 6 | The contents of `../output` are committed to the `output` branch. 7 | 8 | For more information on the CI implementation, see the CI setup documentation in `SETUP.md`. 9 | -------------------------------------------------------------------------------- /ci/deploy.sh: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env bash 2 | 3 | ## deploy.sh: run during a CI build to deploy manuscript outputs to the output and gh-pages branches on GitHub. 4 | 5 | # Set options for extra caution & debugging 6 | set -o errexit \ 7 | -o nounset \ 8 | -o pipefail 9 | 10 | # set environment variables for GitHub Actions 11 | REPO_SLUG=${GITHUB_REPOSITORY} 12 | COMMIT=${GITHUB_SHA} 13 | BRANCH=${DEFAULT_BRANCH:-main} 14 | 15 | # Add commit hash to the README 16 | OWNER_NAME="$(dirname "$REPO_SLUG")" 17 | REPO_NAME="$(basename "$REPO_SLUG")" 18 | export REPO_SLUG COMMIT OWNER_NAME REPO_NAME 19 | envsubst < webpage/README.md > webpage/README-complete.md 20 | mv webpage/README-complete.md webpage/README.md 21 | 22 | # Configure git 23 | git config --global push.default simple 24 | git config --global user.email "$(git log --max-count=1 --format='%ae')" 25 | git config --global user.name "$(git log --max-count=1 --format='%an')" 26 | git checkout "$BRANCH" 27 | 28 | # Configure deployment credentials 29 | MANUBOT_DEPLOY_VIA_SSH=true 30 | git remote set-url origin "git@github.com:$REPO_SLUG.git" 31 | if [ -v MANUBOT_SSH_PRIVATE_KEY ] && [ "$MANUBOT_SSH_PRIVATE_KEY" != "" ]; then 32 | echo >&2 "[INFO] Detected MANUBOT_SSH_PRIVATE_KEY. Will deploy via SSH." 33 | elif [ -v MANUBOT_ACCESS_TOKEN ] && [ "$MANUBOT_ACCESS_TOKEN" != "" ]; then 34 | echo >&2 "[INFO] Detected MANUBOT_ACCESS_TOKEN. Will deploy via HTTPS." 35 | MANUBOT_DEPLOY_VIA_SSH=false 36 | git remote set-url origin "https://$MANUBOT_ACCESS_TOKEN@github.com/$REPO_SLUG.git" 37 | else 38 | echo >&2 "[INFO] Missing MANUBOT_SSH_PRIVATE_KEY and MANUBOT_ACCESS_TOKEN. Will deploy via SSH." 39 | fi 40 | 41 | if [ $MANUBOT_DEPLOY_VIA_SSH = "true" ]; then 42 | # Decrypt and add SSH key 43 | eval "$(ssh-agent -s)" 44 | ( 45 | set +o xtrace # disable xtrace in subshell for private key operations 46 | if [ -v MANUBOT_SSH_PRIVATE_KEY ]; then 47 | base64 --decode <<< "$MANUBOT_SSH_PRIVATE_KEY" | ssh-add - 48 | else 49 | echo >&2 "Deployment will fail since neither of the following environment variables are set: MANUBOT_ACCESS_TOKEN or MANUBOT_SSH_PRIVATE_KEY." 50 | fi 51 | ) 52 | fi 53 | 54 | # Fetch and create gh-pages and output branches 55 | git remote set-branches --add origin gh-pages output 56 | git fetch origin gh-pages:gh-pages output:output || \ 57 | echo >&2 "[INFO] could not fetch gh-pages or output from origin." 58 | 59 | # Configure versioned webpage and timestamp 60 | manubot webpage \ 61 | --timestamp \ 62 | --no-ots-cache \ 63 | --checkout=gh-pages \ 64 | --version="$COMMIT" 65 | 66 | # Commit message 67 | MESSAGE="\ 68 | $(git log --max-count=1 --format='%s') 69 | [ci skip] 70 | 71 | This build is based on 72 | https://github.com/$REPO_SLUG/commit/$COMMIT. 73 | 74 | This commit was created by the following CI build and job: 75 | $CI_BUILD_WEB_URL 76 | $CI_JOB_WEB_URL 77 | " 78 | 79 | # Deploy the manubot outputs to output 80 | ghp-import \ 81 | --push \ 82 | --branch=output \ 83 | --message="$MESSAGE" \ 84 | output 85 | 86 | # Deploy the webpage directory to gh-pages 87 | ghp-import \ 88 | --no-jekyll \ 89 | --follow-links \ 90 | --push \ 91 | --branch=gh-pages \ 92 | --message="$MESSAGE" \ 93 | webpage 94 | 95 | if [ $MANUBOT_DEPLOY_VIA_SSH = "true" ]; then 96 | # Workaround https://github.com/travis-ci/travis-ci/issues/8082 97 | ssh-agent -k 98 | fi 99 | -------------------------------------------------------------------------------- /ci/install-spellcheck.sh: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env bash 2 | 3 | ## install-spellcheck.sh: run during a CI build to install Pandoc spellcheck dependencies. 4 | 5 | # Set options for extra caution & debugging 6 | set -o errexit \ 7 | -o pipefail 8 | 9 | sudo apt-get update --yes 10 | sudo apt-get install --yes aspell aspell-en 11 | wget --directory-prefix=build/pandoc/filters \ 12 | https://github.com/pandoc/lua-filters/raw/13c3fa7e97206413609a48a82575cb43137e037f/spellcheck/spellcheck.lua 13 | -------------------------------------------------------------------------------- /ci/install.sh: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env bash 2 | 3 | ## install.sh: run during an AppVeyor build to install the conda environment 4 | ## and the optional Pandoc spellcheck dependencies. 5 | 6 | # Set options for extra caution & debugging 7 | set -o errexit \ 8 | -o pipefail 9 | 10 | wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge-pypy3-$(uname)-$(uname -m).sh \ 11 | --output-document miniforge.sh 12 | bash miniforge.sh -b -p $HOME/miniconda 13 | source $HOME/miniconda/etc/profile.d/conda.sh 14 | hash -r 15 | conda config \ 16 | --set always_yes yes \ 17 | --set changeps1 no 18 | conda env create --quiet --file build/environment.yml 19 | conda list --name manubot 20 | conda activate manubot 21 | 22 | # Install Spellcheck filter for Pandoc 23 | if [ "${SPELLCHECK:-}" = "true" ]; then 24 | bash ci/install-spellcheck.sh 25 | fi 26 | -------------------------------------------------------------------------------- /content/00.front-matter.md: -------------------------------------------------------------------------------- 1 | {## 2 | This file contains a Jinja2 front-matter template that adds version and authorship information. 3 | Changing the Jinja2 templates in this file may cause incompatibility with Manubot updates. 4 | Pandoc automatically inserts title from metadata.yaml, so it is not included in this template. 5 | ##} 6 | 7 | {## Uncomment & edit the following line to reference to a preprinted or published version of the manuscript. 8 | _A DOI-citable version of this manuscript is available at _. 9 | ##} 10 | 11 | {## Template to insert build date and source ##} 12 | 13 | This manuscript 14 | {% if manubot.ci_source is defined and manubot.ci_source.provider == "appveyor" -%} 15 | ([permalink]({{manubot.ci_source.artifact_url}})) 16 | {% elif manubot.html_url_versioned is defined -%} 17 | ([permalink]({{manubot.html_url_versioned}})) 18 | {% endif -%} 19 | was automatically generated 20 | {% if manubot.ci_source is defined -%} 21 | from [{{manubot.ci_source.repo_slug}}@{{manubot.ci_source.commit | truncate(length=7, end='', leeway=0)}}](https://github.com/{{manubot.ci_source.repo_slug}}/tree/{{manubot.ci_source.commit}}) 22 | {% endif -%} 23 | on {{manubot.generated_date_long}}. 24 | 25 | 26 | {% if manubot.date_long != manubot.generated_date_long -%} 27 | Published: {{manubot.date_long}} 28 | {% endif %} 29 | 30 | 31 | ## Authors 32 | 33 | {## Template for listing authors ##} 34 | {% for author in manubot.authors %} 35 | + **{{author.name}}** 36 | {% if author.corresponding is defined and author.corresponding == true -%}^[✉](#correspondence)^{%- endif -%} 37 | {%- if author.symbol_str is defined -%}{{author.symbol_str}}{%- endif -%} 38 |
39 | {%- set has_ids = false %} 40 | {%- if author.orcid is defined and author.orcid is not none %} 41 | {%- set has_ids = true %} 42 | ![ORCID icon](images/orcid.svg){.inline_icon width=16 height=16} 43 | [{{author.orcid}}](https://orcid.org/{{author.orcid}}) 44 | {%- endif %} 45 | {%- if author.github is defined and author.github is not none %} 46 | {%- set has_ids = true %} 47 | · ![GitHub icon](images/github.svg){.inline_icon width=16 height=16} 48 | [{{author.github}}](https://github.com/{{author.github}}) 49 | {%- endif %} 50 | {%- if author.twitter is defined and author.twitter is not none %} 51 | {%- set has_ids = true %} 52 | · ![Twitter icon](images/twitter.svg){.inline_icon width=16 height=16} 53 | [{{author.twitter}}](https://twitter.com/{{author.twitter}}) 54 | {%- endif %} 55 | {%- if author.mastodon is defined and author.mastodon is not none and author["mastodon-server"] is defined and author["mastodon-server"] is not none %} 56 | {%- set has_ids = true %} 57 | · ![Mastodon icon](images/mastodon.svg){.inline_icon width=16 height=16} 58 | [\@{{author.mastodon}}@{{author["mastodon-server"]}}](https://{{author["mastodon-server"]}}/@{{author.mastodon}}) 59 | {%- endif %} 60 | {%- if has_ids %} 61 |
62 | {%- endif %} 63 | 64 | {%- if author.affiliations is defined and author.affiliations|length %} 65 | {{author.affiliations | join('; ')}} 66 | {%- endif %} 67 | {%- if author.funders is defined and author.funders|length %} 68 | · Funded by {{author.funders | join('; ')}} 69 | {%- endif %} 70 | 71 | {% endfor %} 72 | 73 | † and †† --- These authors contributed equally to this work. 74 | 75 | 76 | ::: {#correspondence} 77 | ✉ — Correspondence possible via {% if manubot.ci_source is defined -%}[GitHub Issues](https://github.com/{{manubot.ci_source.repo_slug}}/issues){% else %}GitHub Issues{% endif %} 78 | {% if manubot.authors|map(attribute='corresponding')|select|max -%} 79 | or email to 80 | {% for author in manubot.authors|selectattr("corresponding") -%} 81 | {{ author.name }} \<{{ author.email }}\>{{ ", " if not loop.last else "." }} 82 | {% endfor %} 83 | {% endif %} 84 | ::: 85 | -------------------------------------------------------------------------------- /content/01.abstract.md: -------------------------------------------------------------------------------- 1 | ## Abstract {.page_break_before} 2 | 3 | Researchers in ecology and evolutionary biology are increasingly dependent on computational code to conduct research. 4 | Hence, the use of efficient methods to share, reproduce, and collaborate on code as well as document research is fundamental. 5 | GitHub is an online, cloud-based service that can help researchers track, organize, discuss, share, and collaborate on software and other materials related to research production, including data, code for analyses, and protocols. 6 | Despite these benefits, the use of GitHub in ecology and evolution is not widespread. 7 | To help researchers in ecology and evolution adopt useful features from GitHub to improve their research workflows, we review twelve practical ways to use the platform. 8 | We outline features ranging from low to high technical difficulty: storing code, managing projects, coding collaboratively, conducting peer review, and writing a manuscript. 9 | Given that members of a research team may have different technical skills and responsibilities, we describe how the optimal use of GitHub features may vary among members of a research collaboration. 10 | As more ecologists and evolutionary biologists establish their workflows using GitHub, the field can continue to push the boundaries of collaborative, transparent, and open research. 11 | -------------------------------------------------------------------------------- /content/03.use-cases-a.md: -------------------------------------------------------------------------------- 1 | ## Twelve practical ways GitHub can accelerate research in ecology and evolution 2 | 3 | ### Storing and sharing research compendia {#storing-sharing} 4 | 5 | 6 | An EEB research compendium includes all computational materials related to research production, including data, code for analyses and protocols. 7 | Safely storing these files is essential to protect against accidental modifications or deletions. 8 | Many researchers begin using GitHub to backup their research compendium [@doi:10.1080/00031305.2017.1375986] into a centralized, readily-available remote server (see [Box 1](#definitions)). 9 | This practice has the advantages of facilitating collaboration, integrating data and code archiving, allowing file versions to be accessed and restored, and further contributing to open science practices [@doi:10.1162/99608f92.9497f68e]. 10 | Changes made to files in version-controlled repositories are accompanied by authored descriptions of modifications ([Box 1](#definitions)). 11 | Later, the entire history of commits and their commit messages are viewable and can be audited similarly to physical laboratory notebooks [@doi:10.1186/1751-0473-8-7]. 12 | GitHub allows administrative control over who can view and modify repositories, and the process of cloning, forking and suggesting changes through pull requests (see [Box 1](#definitions)) ensures code owners have full control over code and documents. 13 | Repositories can be changed from public to private, allowing data storage and management without sacrificing the privacy that may be necessary for certain compendia. 14 | With this, researchers can grant collaborators read and/or write access to files in private repositories to pursue pre-publication analyses or writing in privacy. 15 | 16 | GitHub limits committed file sizes to 100 Mb (megabytes) [@url:https://docs.github.com/en/repositories/working-with-files/managing-large-files/about-large-files-on-github], which may require external file storage alternatives (such as local or cloud-hosting) for some parts of research compendia. 17 | However, users can still track versions of remotely- or locally-stored files in their repositories using Git Large File Storage (). 18 | 19 | ### Project continuity 20 | 21 | 22 | 23 | Projects in ecology and evolution often involve research professionals holding limited-term positions, such as graduate students, research assistants, and post-doctoral fellows [@doi:10.5334/jors.307]. 24 | Without clear plans on project continuity, research code and data management upkeep tends to fall off as researchers move on to new projects or other institutions. 25 | Additionally, code and data can be difficult to access and recover when kept only on personal devices [@doi:10.1016/j.cub.2013.11.014]. 26 | 27 | GitHub can facilitate project continuity in research by making code and data handover between users easier [@doi:10.5334/jors.307; @doi:10.1186/1751-0473-8-7]. 28 | Through version control, the history of code and data from projects in ecology and evolution becomes accessible to future laboratory members and collaborators [@doi:10.1038/s41559-017-0160]. 29 | Repositories and organizations can have designated data and code owners [or more appropriately, "data stewards"; see @doi:10.1890/ES14-00402.1, @url:https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners], who can also change through time, allowing for the transition of code between research cohorts (see also ["Organizing and managing teams"](#organizations)). 30 | Other project collaborators can contribute to repository design and development, and their active involvement can both aid authors ability to act as guarantors, and the clarity and reproducibility of the project for future users. 31 | In (Figure @fig:github-diagram), we highlight several elements of recommended repository structure, and the various ways that contributors may interact with them. 32 | 33 | Software compatibility during the analysis and reanalysis of project data can be ensured by storing information about software dependencies and their versions within the same project repository. 34 | With more advanced practices, one can remotely install and execute scripts using specific versions of software within GitHub's project automation tools, GitHub Actions (see below). 35 | 36 | In addition to projects, long-term management of laboratory materials (such as notebooks or experimental protocols) can also be done within GitHub, a practice that has been increasingly adopted across many fields [@doi:10.1038/538127a], including applied ecology (_e.g._, ), biogeography and global change biology (_e.g._, ), and microbial ecology (_e.g._, ). 37 | 38 | 39 | ### Project management 40 | 41 | 42 | 43 | Modern research in ecology and evolution is highly collaborative, bringing together multidisciplinary teams from various institutions [@doi:10.1890/120370]. 44 | On GitHub, collaborators can share feedback, brainstorm ideas, and troubleshoot problems (Figure @fig:github-diagram). 45 | Project management can happen via three GitHub repository features: "Issues", "Discussion" and "Projects" ([Box 1](#definitions)). 46 | Github Issues allow for discrete tasks and sub-tasks to be identified, assigned to team members, and categorized with custom labels. 47 | Github Discussions serve as a message board for conversation. 48 | Finally, GitHub Projects provides users with real-time tracking of project priorities and status [@url:https://docs.github.com/en/issues/trying-out-the-new-projects-experience/about-projects]. 49 | For instance, one can create a discussion on a project repository to decide which method to apply for biodiversity data analysis. 50 | Then, an issue can be created to establish steps and responsibilities including data formatting, statistical analyses, figure generation, and issue resolution. 51 | For example, sPlotOpen [@10.1111/geb.13346] manuscript repository contains issues and discussions tracking the development of the project (see ). 52 | Using GitHub for all project-related conversation and planning, rather than email or messaging tools, makes it easier to keep track of progress throughout the lifespan of a project. 53 | However, one can opt to receive new issues, discussions, and responses as emails and can post replies by email as well. 54 | This allows for centralized communication for a team even when some members prefer to use email for communication. 55 | Unlike emails and messages which can get lost as more new tasks arise, GitHub issues are intentionally closed by repository administrators hiding the issue from view (closed issues remain accessible but not immediately visible). 56 | 57 | ### Educational materials 58 | 59 | 60 | 61 | GitHub supports a broad set of mechanisms for hosting educational materials. 62 | The entire process of running a course, workshop, or lecture, can all be done openly on GitHub including material development, web hosting, and delivery, and even submission and grading of assignments. 63 | While there are other purpose-built platforms for this, GitHub provides a free, open-source alternative. 64 | 65 | Syllabi, presentations, and other course materials can be version-controlled, stored and managed in GitHub. 66 | While any file type for presentations and documents can be stored and tracked in repositories, GitHub can directly render and display certain markup languages, such as HyperText Markup Language (HTML) and Markdown documents, making these file types especially useful for educational materials. 67 | Course content can then be delivered to the audience by sharing links of web-hosted GitHub Pages (see [Hosting a Website](#hosting-a-website)), GitHub Repositories and/or GitHub Organizations. 68 | Finally, instructors can host and assign student work to be submitted collaboratively or individually as code and text files, and even build autograding tests using the GitHub Classroom tool (). 69 | 70 | Although time-consuming, adopting these features in classrooms can integrate the learning of version-control and GitHub practices with the learning of course contents, and thus boost students' feelings of self-efficacy and confidence [@doi:10.1187/cbe.13-12-0241]. 71 | -------------------------------------------------------------------------------- /content/04.use-cases-b.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | ### Hosting a website{#hosting-a-website} 4 | 5 | 6 | Personal or laboratory websites can improve the sharing of research findings, build online presence, and increase coordination of research efforts [@doi:10.1038/nj7142-347a]. 7 | Despite researchers in ecology and evolution generally lacking experience in building or hosting webpages, many tools have been developed to help this process. 8 | Static websites can now be easily built [using, for example Quarto (), RMarkdown, Hugo (), GitHub Website templates ()), stored in a repository, and be readily hosted by activating GitHub's Pages () feature. 9 | Creating and hosting websites on GitHub Pages is more complex than out-of-the-box platforms (_e.g._, Wix, Weebly, Google Sites). 10 | However, free hosting, widely available template customization, and versioning are strong advantages over alternatives. 11 | 12 | ### Archiving citable code and data{#archiving-citable-code} 13 | 14 | 15 | 16 | Government, funding agencies, and publishers exercise rigorous open access data policies and mandates [@doi:10.1371/journal.pone.0229003; @doi:10.1108/TG-03-2014-0008]. 17 | However, code and data sharing may be met by individual reluctance, temporary embargoes, or partially prevented by privacy and confidentiality reasons [@doi:10.1371/journal.pone.0026828; @doi:10.3389/fpubh.2017.00327; @doi:10.1371/journal.pone.0134826]. 18 | Still, data deposition and ensuring its availability can amplify the outreach of published studies [@doi:10.7717/peerj.1242], increase citation rates [@doi:10.1371/journal.pone.0000308], and among many other reasons, enable the reproducibility and robustness of scientific advances [@doi:10.1038/ncb3506; @doi:10.1016/j.tree.2015.11.006; @doi:10.1038/533452a]. 19 | While public repositories on GitHub make it easy to store and share data files, they are not considered long-term repositories for research materials. 20 | This is because GitHub, a for-profit company, does not have long-term data availability guarantees, allowing users to delete or make repositories private after publication. 21 | Also, GitHub does not issue Digital Object Identifiers (DOI) for content uploaded to their servers. 22 | DOIs are persistent and citable unique alpha-numeric identifiers assigned to digitally-stored research materials. 23 | Because of this, scientists sharing code and data through GitHub are strongly encouraged to independently submit their research materials to long-term data archives (_e.g._, Zenodo, Figshare, Dryad, OSF [@doi:10.1038/538127a; @doi:10.1371/journal.pcbi.1004947; @doi:10.1029/2021EA001797]; [Table 1](#tbl:compare)). 24 | Some of these options (Zenodo, Figshare and OSF) integrate with GitHub, allowing project, code, and data releases ([Box 1](#definitions)) to be archived with versioned, citable DOIs. 25 | Linking GitHub repositories with a DOI helps research become findable, properly cited, and can ensure long-term stability [@doi:10.1890/ES14-00402.1]. 26 | This strategy has been increasingly adopted in numerous studies in ecology and evolution (_e.g._, the Zenodo repositores @10.5281/zenodo.6097109, @doi:10.5281/zenodo.1188710; the Dryad and OSF repositories @doi:10.5061/dryad.rjdfn2zgj and @doi:10.17605/OSF.IO/AMVP5). 27 | 28 | An important aspect of making code and data citable and reusable is to add an appropriate license to protect intellectual property. 29 | Code published without a license is under exclusive copyright (by default), protecting it from copy, distribution, and modifications. 30 | One may grant specific rights to their code for reuse by adding licensing files and specifications within GitHub repositories [@url:https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-license-to-a-repository]. 31 | The Choose a License () website offers further guidance on the licenses available for research and creative products. 32 | For example, Creative Commons (CC; ) licenses can specify that shared code is intended for a specific analysis. 33 | A CC BY 4.0 license specifies that any code (or other creative products) must be appropriately credited to its original author when distributed, adapted or reused. 34 | 35 | 36 | ### Collaborative and asynchronous code editing{#code-editing} 37 | 38 | 39 | 40 | GitHub can serve as a platform for everyone working with research (_e.g._, supervisors or advisors, graduate students, postdoctoral fellows, and collaborators) to share in-progress work, and flag specific challenges or questions for each other ([Table 2](#tbl:roles)). 41 | Periodic code, data and text review is useful for identifying errors early in the research process [@doi:10.1145/3341525.3387370], and informing further training and mentorship to fill gaps in skills. 42 | This is facilitated by a group of core features of Git and GitHub that allow contributors to discuss and simultaneously work on a project. 43 | For instance, users can clone and fork repositories (see [Box 1](#definitions)), allowing for modifications to be done on a linked copy of a repository, which can then later be merged into the main project through pull requests. 44 | Collaborators can comment on specific lines of code and text or suggest changes, which can then be incorporated with the click of a button, greatly facilitating peer review. 45 | Explicit project organization and increased communication within pull requests, in GitHub Issues, or in GitHub Discussions can help with project development and with potential merge conflicts due to users simultaneously working on the same sections. 46 | Moreover, version control allows researchers to make changes in code or documents without worrying about irreparably modifying someone else's work (#storing-sharing). 47 | 48 | By enabling more comprehensive remote collaboration, GitHub encourages the exchange of ideas among researchers at different institutions and in different countries, which can serve to improve the quality of the research itself by providing open access to data and code. 49 | 50 | ### Writing a manuscript{#writing-manuscript} 51 | 52 | 53 | 54 | Beyond supporting collaborative code development, GitHub can be used for writing manuscripts. 55 | Writing a manuscript and storing its associated data and code in GitHub increases scientific reproducibility because text, code, and data can be found in one place. 56 | Although it may involve more initial time investment for setup, GitHub has many features that support a powerful collaborative workflow when writing manuscripts [@doi:10.1186/1751-0473-8-7]. 57 | Text documents stored and versioned in GitHub can be instantly displayed when written in Markdown, a lightweight markup language increasingly popular among scientists. 58 | When manuscripts are written in Markdown on GitHub, co-authors can contribute changes or suggest revisions to a manuscript in the same ways they would contribute changes or suggest revisions to code (see [Collaborative and asynchronous code editing](#code-editing)). 59 | Relevant literature or issues can be suggested using the Discussions and Issues features. 60 | 61 | Incorporating GitHub into the process of writing a manuscript does not necessarily mean pivoting to an entirely new workflow. 62 | For instance, authors who prefer writing in LaTeX or Markdown can synchronize Overleaf [@url:https://www.overleaf.com/learn/how-to/Using_Git_and_GitHub], HackMD (), and other platforms directly with a GitHub repository. 63 | Similar GitHub integrations are available for projects stored in DropBox, Google Drive, among other popular tools familiar to many scientists and their collaborators ([Table 1](#tbl:compare)). 64 | 65 | We wrote this manuscript using Manubot, a modifiable workflow implemented in GitHub to automatically render manuscripts and automate bibliographical tasks [@doi:10.1371/journal.pcbi.1007128]. 66 | Manubot uses GitHub's automation workflow, GitHub Actions, to combine and convert individual Markdown files into a single LaTeX document, which can then be converted to a Word or PDF document, and displayed as a webpage. 67 | Citations and bibliographic references are automatically managed with citable persistent identifiers (_e.g._, DOI, PubMed ID, ISBN, URL). 68 | The resulting manuscript can be rendered with document templates and citation style language formatting to meet journal formatting requirements. 69 | Every change made to the manuscript triggers its rendering, so that updates are readily displayed and made publicly available. 70 | Additional GitHub Actions can be integrated with Manubot, such as ones creating figures or generating tables (_e.g._, ). 71 | 72 | ### Peer review{#peer-review} 73 | 74 | 75 | 76 | Peer review is the standard process for assessing whether research done in ecology and evolution should be published in a scientific journal. 77 | GitHub provides an open and transparent platform that can be used for either directly providing feedback on research products or addressing changes recommended by reviewers. 78 | GitHub Issues can be used to organize and discuss reviewer suggestions and to assign them to co-authors (_e.g._, ). 79 | When reviewer comments are posted as separate issues, authors can comment on the issues to discuss possible changes and assign co-authors who will address the issue. 80 | Co-authors can then integrate their edits and responses to reviewers using pull requests, which can be directly linked to the issues they address. 81 | 82 | GitHub can also assist reviewers during the peer review process. 83 | If the code associated with a manuscript is made available at the time of submission (_e.g._, as a link to a GitHub repository within the Data Availability Statement), peer reviewers may be able to offer more comprehensive suggestions on the code and written materials, potentially recognizing errors before publication. 84 | Certain journals or software development communities require submitted work or research code to be hosted on GitHub and their review processes make use of GitHub Issues (_e.g._, rOpenSci (), Journal of Open Source Software (). 85 | -------------------------------------------------------------------------------- /content/05.use-cases-c.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | ### Open science discussion 4 | 5 | 6 | 7 | Scientific publications often omit part of their intellectual and computational workflows, including the treatment of raw data and analytical steps (_e.g._, model assumption testing). 8 | Publishing data and reproducible workflows along with manuscripts can provide readers with all details about analytical steps and enable reproducing research experiments and results [@doi:10.1371/journal.pbio.3000763]. 9 | In addition to storing data and code, GitHub repositories can provide a time-stamped (version controlled) preregistration of research plans and hypotheses. 10 | 11 | Conventional research practices typically separate tasks among collaborators (_i.e._, data entry, analysis, writing). 12 | It is common that coauthors discuss, but do not actively verify, edit, or execute research tasks that are not their main responsibility. 13 | GitHub can serve as a tool for open and tractable research development. 14 | Collaborators can directly interact with code and data, inspect for errors, and potentially identify scientific misconduct prior to manuscript submission [_e.g._, @doi:10.1038/d41586-022-02156-2; @doi:10.1038/d41586-020-00287-y; ]. 15 | Collaborators and readers are better positioned to discover erroneous or questionable findings if they have complete and transparent access to projects. 16 | 17 | This transparency can be extended beyond co-authors to the entire scientific community and to the public. 18 | Supplying code for novel or currently used methods reduces barriers to knowledge, improving the ability of others to build on existing work. 19 | This practice results in greater proliferation and accessibility for a broader audience. 20 | Projects can make use of GitHub Discussions () to communicate among repository members (collaborators) and to engage with other scientists and the general public. 21 | Moreover, researchers can also use the GitHub Community () forum to share expertise or request help from others on their analyses and ideas ([Table 2](#tbl:roles)). 22 | 23 | The desire or need for privacy during the developmental stages of a manuscript or of a larger research project is common in EEB, and this is often perceived as a major barrier to doing science openly. 24 | Because GitHub repositories can be made private or public at any time, there is no need to choose privacy over open science, or vice-versa. 25 | Repositories can be kept private until their contents are ready to be shared publicly, as might occur when a research article is published or when an embargo is lifted. 26 | 27 | ### Automation 28 | 29 | 30 | 31 | Automation has the strong potential to expand the scale and pace of research in ecology and evolution [@doi:10.1126/science.abi4692]. 32 | Automation frameworks can streamline many stages of the scientific process, including data collection and data validation [_e.g._, @doi:10.3389/fevo.2021.679673; @doi:10.1371/journal.pbio.3000125], data analysis [_e.g._, @doi:10.1038/nbt.3780], unit testing of research code [_e.g._, @doi:10.12688/f1000research.9315.1], archiving and deployment of data, code and reports [_e.g._, this manuscript, @doi:10.1111/2041-210X.13104], and the interpretation, integration and usage of data and software across different sources [see @doi:10.1038/sdata.2017.114]. 33 | In this context, small modifications to code and data can be frequently committed and automatically tested, as in continuous integration and continuous deployment practices [@doi:10.1109/MS.2014.58]. 34 | This allows for early detection and correction of errors, potentially improving confidence in scientific development by minimizing software errors [see @doi:10.12688/f1000research.5930.2]. 35 | In addition to increasing scientific rigour and confidence in ecological software [@doi:10.1890/080141], automation can help advance more rapidly sharing ecological data and making sure the data are high quality [@doi:10.1073/pnas.1710231115]. 36 | Integrating automation workflows has been highly encouraged in areas of EEB, including predictive ecology [@doi:10.1111/ele.13994], long-term ecological studies [@doi:10.1371/journal.pbio.3000125; @doi:10.1101/332783], and management of species at risk information [@doi:10.1038/s41597-022-01381-8]. 37 | 38 | Automation can be integrated into GitHub repositories through the GitHub Actions feature [@url:https://github.com/features/actions], or through alternative automation systems [_e.g._, Circle CI, @url:https://circleci.com]; Travis CI, @url:https://www.travis-ci.com]. 39 | Users can set up workflows associated with their repositories that are triggered by events (_e.g._, push, pull request or at specified times) for remote servers to perform user-specified steps and actions. 40 | These actions are highly configurable and have numerous applications, such as automatically running analyses and creating figures when data or code are updated, incorporating changes to websites or applications, testing modifications to software (_e.g._, R or Python libraries). 41 | Action workflows can be found in GitHub's Marketplace () or, alternatively, in open user repositories. 42 | 43 | ### Organizing and managing teams{#organizations} 44 | 45 | 46 | 47 | GitHub Organizations are shared virtual spaces that allow teams to work in different repositories, while remaining tied together under a larger group, such as a laboratory, department, or project involving several teams. 48 | Organizations allow larger projects with many steps or moving parts to be constrained to one virtual space, where outputs and sub-projects can be easily accessed and located without relying on individuals. 49 | Because the repositories are grouped, members can reference and contribute to each other's work without necessarily being part of the same repository, broadening the accessibility and longevity of code and writing contributions. 50 | 51 | Contributors can be assembled into teams within an organization, which allows administrators to assign roles, tasks, and repository modification permissions to organization members. 52 | Whereas access to repositories is usually assigned to individual contributors, Organizations facilitate the management of access permissions by allowing teams to be granted access to specific repositories. 53 | This ensures repositories with sensitive information remain as restricted as needed, while others stay open and accessible to selected member groups. 54 | The organization structure also allows for issue tracking and discussions related to research content and progress. 55 | 56 | As an example, GitHub Organizations are particularly well-suited to host documents and projects within a laboratory, such as research compendia, codes of conduct, protocols, training documents, and other relevant documents that evolve collaboratively over time. 57 | In this way, teams have full ownership of repositories within an organization, while ensuring that these materials stay accessible to the laboratory after people have moved on or when locally-stored data are lost. 58 | This application extends to research centres, which may include several distinct projects that remain linked to institutions [_e.g._, the German Centre for Integrative Biodiversity Research (iDiv, )]. 59 | The team organizing the hackathon which inspired this article used a GitHub Organization (SORTEE-Github-Hackathon, ) to centralize the project development, from meeting notes to, ultimately, this manuscript. 60 | Organizations are also convenient for hosting learning materials, including lectures or workshops, such as the Québec Centre for Biodiversity Science R Workshop Series (QCBSRworkshops, ) or the University of Edinburgh's Coding Club (Coding Club, ), which may be continuously updated by an ever-evolving group of contributors. 61 | -------------------------------------------------------------------------------- /content/07.conclusion.md: -------------------------------------------------------------------------------- 1 | ## Conclusion 2 | 3 | We provide twelve practical ways that ecologists and evolutionary biologists can use GitHub to improve their research workflow, make it more open, reproducible and transparent. 4 | We provide definitions ([Box 1](#definitions)) and types of users (Figure @fig:github-diagram) to help researchers identify and prioritize the skills and tools to learn and apply. 5 | We highlight tools providing high collaborative potential (_e.g._, open science discussion, collaborative code editing) to more individual focused (_e.g._, storing code and data, building a website). 6 | We argue that the tools readily available in GitHub have the potential to make ecology and evolution more open, reproducible and transparent. 7 | With this comprehensive review of how EEB researchers can use GitHub, we encourage researchers at any career stage to adopt GitHub as a platform for sharing and collaboration. 8 | -------------------------------------------------------------------------------- /content/08.statements.md: -------------------------------------------------------------------------------- 1 | ## Author Contributions 2 | We indicate author contributions using the [CRediT Taxonomy](https://casrai.org/credit/). 3 | 4 | - Conceptualization: RCO, BPME, KH, EJH, LLSR, PHPB 5 | - Investigation: RCO, BPME, KH, EJH, LLSR, ERS, MJG, VF, ADB, CBB, KMG, SSHS, AG, FH, HW, DGEG, PHPB 6 | - Methodology: RCO, BPME, KH, EJH, LLSR, PHPB 7 | - Project Administration: RCO, PHPB 8 | - Software: RCO, BPME, KH, EJH, LLSR, ERS, MJG, VF, ADB, CBB, KMG, SSHS, AG, FH, HW, DGEG, PHPB 9 | - Visualization: RCO, BPME, KH, EJH, LLSR, ERS, MJG, VF, ADB, CBB, KMG, SSHS, AG, FH, HW, DGEG, PHPB 10 | - Writing - Original Draft: RCO, BPME, KH, EJH, LLSR, ERS, MJG, VF, ADB, CBB, KMG, SSHS, AG, FH, HW, DGEG, PHPB 11 | - Writing - Review and Editing: RCO, BPME, KH, EJH, LLSR, ERS, MJG, VF, ADB, CBB, KMG, SSHS, AG, FH, HW, DGEG, PHPB 12 | - Resources: PHPB 13 | - Revisions: PHPB, ERS, RCO, KH, EH, FH 14 | 15 | ## Acknowledgements 16 | 17 | This manuscript arose from a hackathon at the Society for Open, Reliable, and Transparent Ecology and Evolution (SORTEE) virtual meeting in July 2021. 18 | We thank Ciera Martinez for being a co-organizer of the SORTEE hackathon that started our discussion on GitHub in EEB and for creating our hackathon website on GitHub. 19 | 20 | RCO was funded by the U.S. Department of Energy, Office of Science, Office of Biological and Environmental Research, Earth and Environmental Sciences Division, Data Management program under contract number DE-AC02-05CH11231. 21 | PHPB was supported by the Science without Borders program and the Brazilian National Council for Research and Technological Development (CNPq-SwB-GDE 142493/2013-0). 22 | 23 | ## Code and data availability 24 | 25 | The source code and data for this manuscript are available at . 26 | The source code will be archived in the ESS-DIVE data repository prior to publication. 27 | 28 | ## Conflict of Interest Statement 29 | On July 15, 2022, RCO was offered a position to work at GitHub and became an employee on August 23, 2022. 30 | Initial discussion of publishing this manuscript began in July 2021 and all work on the manuscript prior to the first revision was done while RCO was an employee at Lawrence Berkeley National Laboratory. 31 | The authors declare that there is no conflict of interest that could be perceived as prejudicing the impartiality of the research reported. -------------------------------------------------------------------------------- /content/09.figures-tables.md: -------------------------------------------------------------------------------- 1 | ## Figures {.page_break_before} 2 | 3 | ![An overview of Git's core features. A) Multi-faceted components allow for code writing, small data storage, manuscript writing, and project management to all be done in one place. `CONTRIBUTING.md`, `LICENCE.md`, and `README.md` files allow new team members, or others wanting to use materials, to understand the project components and learn how they can engage with the project and existing team members. B) Issues, Pull Requests, Discussions, and Projects allow for team members to ask for feedback, suggest fixes, discuss related ideas, and keep track of all the moving parts of a project. C) All collaborators on a project can be a part of a single repository, with varying push privileges and responsibilities.](images/Figure1.png){#fig:github-diagram} 4 | 5 | 6 | 7 | ![A summary of ways GitHub can be used showing technical difficulty and degree of collaboration for each. Activities higher on the vertical axis require usage knowledge of more GitHub features than activities lower on the axis. On the horizontal axis, each activity spans a region representing who is potentially involved with or benefits from each activity. For example, storing data and code mainly benefits individual researchers or members of a laboratory while making data and code citable and reproducible benefit other labs and the larger community as well. Independently of ones knowledge of GitHub features, there are ways to use GitHub that allow tapping unto one of the strongest benefits of the platform: facilitating and enhancing collaboration. For information on the methods and the data used to create this figure, see Appendix S1.1, Appendix S1.2, and Tables S1.1 and S1.2.](images/scatterblob_1-viridis-turbo.png){#fig:scatterblob} 8 | 9 | 10 | 11 | ## Tables 12 | -------------------------------------------------------------------------------- /content/10.comparison_table.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | | Guild | Software | Version control | Cloud-storage backup | Passive collaboration | Active real-time collaboration | Does it provide a reasonably unrestrictive free version? | Is it permanent (e.g. through a DOI)? | Storage limits | GitHub Integration | 4 | |:-------------------------------------|:-------------------------------|:----------------|:---------------------|:----------------------|:-------------------------------|:------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------------| 5 | | Multi-tool | GitHub | Yes | Yes | Yes | No | Broadly used free version. Advanced features are provided for free to students and education professionals. | A DOI can only be obtained when integrating to other services that can mint a DOI (e.g., Zenodo, OSF). | 100 MB per file, 500 MB per private repository (2 GB for paid accounts). 100 GB for public repositories. Larger files (up to 2 GB) can be attached to releases. | Not applicable. | 6 | | Multi-tool | Open Science Framework | Yes | Yes | Yes | Yes | Yes. | Yes | 25 GB for private projects, up to 5 GB per file, plus partner add-ons, 50 GB for public projects | Yes | 7 | | Long-term (public) data repositories | PANGAEA | Yes | Yes | Yes | No | Yes. | Yes | 10 GB free | No | 8 | | Long-term (public) data repositories | Zenodo | After published | After published | Yes | No | Yes. | Yes | 50 GB per dataset | Yes | 9 | | Long-term (public) data repositories | Dryad | After published | After published | Yes | No | No, however certain journals cover costs. | Yes | 300 GB per publication | No. | 10 | | Long-term (public) data repositories | Figshare | Yes | Yes | Yes | No | Yes. | Yes | 20 GB free, up to 5 TB | Yes | 11 | | Temporary (personal) drive storage | Google Drive | Yes | Yes | Yes | Yes | Free version is restrictive. | No | 15GB free, up to 100GB with Google One | Yes | 12 | | Temporary (personal) drive storage | Box | Limited | Yes | Yes | Yes | No. | No | UnLimited total size for subscription | Yes | 13 | | Temporary (personal) drive storage | DropBox | Limited | Yes | Yes | Yes | Free version is restrictive. | No | 2 GB free | Yes | 14 | | Temporary (personal) drive storage | OneDrive and the Office Suite | Yes | Yes | Yes | Yes | Free version is restrictive. | No | 5 GB free, up to 1TB paid | Yes | 15 | | Collaborative code and text editors | Overleaf (online latex editor) | Yes | Yes | Yes | Yes | Free version is restrictive. Only affiliated institutions (majority from the Global North) obtain premium access. | No | 1 MB for individual LaTeX files, 50MB for individual files, unlimited project size. | Yes | 16 | | Collaborative code and text editors | Jupyter Notebook | Yes | Yes | Yes | With Colab | Yes. | No | via Binder: no hard limit, but suggests no files \>100MB, can also store on GitHub or Google Colab | Yes | 17 | | Collaborative code and text editors | HackMD | Yes | Yes | Yes | Yes | Free version is moderatively restrictive. | No | 3 documents free, private invitee limits | Yes | 18 | | Collaborative code and text editors | Colaboratory | Yes | Yes | Yes | Yes | Free version is moderatively unresitrcitve, unless high computational resources are required. | No | Colab that is free of charge notebooks can run for at most 12 hours. File storage is bounded to Google Drive’s limitations. 12 GB GPU RAM . | No. | 19 | 20 | Table: A comparison of technologies commonly used for collaborating on research 21 | in Ecology and Evolutionary Biology. In the first column, we group 22 | platforms for collaboration into broad guilds. The second column lists 23 | the platform for collaboration. The remaining columns indicate whether 24 | the platform for collaboration includes certain features {#tbl:compare} 25 | 26 | 27 | -------------------------------------------------------------------------------- /content/11.roles_table.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | | Role | GitHub repository | README | Issue | Discussion | Pull Request | Fork | GitHub Pages | 4 | |:-----------------|:---------------------------------------------------|:-------------------------------------|:--------------------------------------------------------|:---------------------------------------|:-----------------------------------------------------|:-------------------------------------------------|:-------------------------------------------------------| 5 | | Project manager | Set contributor permissions, share code of conduct | Project description, citation, DOIs | Assign tasks to collaborators | Discuss project directions and goals | Approve and incorporate edits to code and/or writing | | Share up-to-date reports, figures, or draft manuscript | 6 | | Co-author | Edit Markdown text or add files | | Propose changes involving code (e.g. analyses, figures) | Discuss proposed changes to manuscript | | | | 7 | | Code contributor | | | Suggest code changes | | Contribute changes to code, initiate code review | | Contribute to project website | 8 | | Code reviewer | Find all code related to a project | | Highlight specific lines of code and make suggestions | | Review or recommended changes in code | | | 9 | | Community | | | Suggest additional features and report bugs | Ask questions about data and code | | Create a linked, editable copy of the repository | View project website | 10 | 11 | Table: A non-exhaustive collection of ideas for how various GitHub 12 | features could be utilized for a research project. Here we have 13 | categorized contributors/collaborators into five roles. A Project 14 | Manager owns the GitHub repository for a project, and leads the academic 15 | project (e.g., lead author of a manuscript). A co-author contributes to 16 | writing and other aspects of research, but may have limited or no 17 | experience with programming, git, and/or GitHub. A code contributor 18 | writes or edits analysis code for the project. A code reviewer could be 19 | a project collaborator or a peer reviewer who reviews project code. They 20 | are familiar with coding, but not necessarily with git or GitHub (but 21 | they are willing to learn). Finally, community members could be other 22 | researchers or non-researchers interested in reproducing results, 23 | re-using code or data, or communicating with researchers involved in the 24 | project. These roles are not mutually exclusive—a co-author could also 25 | be a code contributor and code reviewer, for example. For definitions of 26 | the GitHub features, see Box 1. {#tbl:roles} 27 | 28 | 29 | -------------------------------------------------------------------------------- /content/90.back-matter.md: -------------------------------------------------------------------------------- 1 | ## References {.page_break_before} 2 | 3 | 4 |
5 | -------------------------------------------------------------------------------- /content/images/Fig1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SORTEE-Github-Hackathon/manuscript/8d5bc4ece59c37b94e74db337e837df52f6ac713/content/images/Fig1.png -------------------------------------------------------------------------------- /content/images/Fig1.xcf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SORTEE-Github-Hackathon/manuscript/8d5bc4ece59c37b94e74db337e837df52f6ac713/content/images/Fig1.xcf -------------------------------------------------------------------------------- /content/images/Figure1.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SORTEE-Github-Hackathon/manuscript/8d5bc4ece59c37b94e74db337e837df52f6ac713/content/images/Figure1.pdf -------------------------------------------------------------------------------- /content/images/Figure1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SORTEE-Github-Hackathon/manuscript/8d5bc4ece59c37b94e74db337e837df52f6ac713/content/images/Figure1.png -------------------------------------------------------------------------------- /content/images/github.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | -------------------------------------------------------------------------------- /content/images/mastodon.svg: -------------------------------------------------------------------------------- 1 | 2 | 14 | 16 | 36 | 41 | 45 | 46 | -------------------------------------------------------------------------------- /content/images/orcid.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | -------------------------------------------------------------------------------- /content/images/roles.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SORTEE-Github-Hackathon/manuscript/8d5bc4ece59c37b94e74db337e837df52f6ac713/content/images/roles.png -------------------------------------------------------------------------------- /content/images/scatterblob_0.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SORTEE-Github-Hackathon/manuscript/8d5bc4ece59c37b94e74db337e837df52f6ac713/content/images/scatterblob_0.pdf -------------------------------------------------------------------------------- /content/images/scatterblob_0.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SORTEE-Github-Hackathon/manuscript/8d5bc4ece59c37b94e74db337e837df52f6ac713/content/images/scatterblob_0.png -------------------------------------------------------------------------------- /content/images/scatterblob_1-darjeeling.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SORTEE-Github-Hackathon/manuscript/8d5bc4ece59c37b94e74db337e837df52f6ac713/content/images/scatterblob_1-darjeeling.pdf -------------------------------------------------------------------------------- /content/images/scatterblob_1-darjeeling1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SORTEE-Github-Hackathon/manuscript/8d5bc4ece59c37b94e74db337e837df52f6ac713/content/images/scatterblob_1-darjeeling1.png -------------------------------------------------------------------------------- /content/images/scatterblob_1-darjeeling2.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SORTEE-Github-Hackathon/manuscript/8d5bc4ece59c37b94e74db337e837df52f6ac713/content/images/scatterblob_1-darjeeling2.pdf -------------------------------------------------------------------------------- /content/images/scatterblob_1-darjeeling2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SORTEE-Github-Hackathon/manuscript/8d5bc4ece59c37b94e74db337e837df52f6ac713/content/images/scatterblob_1-darjeeling2.png -------------------------------------------------------------------------------- /content/images/scatterblob_1-royal2.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SORTEE-Github-Hackathon/manuscript/8d5bc4ece59c37b94e74db337e837df52f6ac713/content/images/scatterblob_1-royal2.pdf -------------------------------------------------------------------------------- /content/images/scatterblob_1-royal2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SORTEE-Github-Hackathon/manuscript/8d5bc4ece59c37b94e74db337e837df52f6ac713/content/images/scatterblob_1-royal2.png -------------------------------------------------------------------------------- /content/images/scatterblob_1-viridis-turbo.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SORTEE-Github-Hackathon/manuscript/8d5bc4ece59c37b94e74db337e837df52f6ac713/content/images/scatterblob_1-viridis-turbo.pdf -------------------------------------------------------------------------------- /content/images/scatterblob_1-viridis-turbo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SORTEE-Github-Hackathon/manuscript/8d5bc4ece59c37b94e74db337e837df52f6ac713/content/images/scatterblob_1-viridis-turbo.png -------------------------------------------------------------------------------- /content/images/scatterblob_1-zissou1.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SORTEE-Github-Hackathon/manuscript/8d5bc4ece59c37b94e74db337e837df52f6ac713/content/images/scatterblob_1-zissou1.pdf -------------------------------------------------------------------------------- /content/images/scatterblob_1-zissou1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SORTEE-Github-Hackathon/manuscript/8d5bc4ece59c37b94e74db337e837df52f6ac713/content/images/scatterblob_1-zissou1.png -------------------------------------------------------------------------------- /content/images/scatterblob_1.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SORTEE-Github-Hackathon/manuscript/8d5bc4ece59c37b94e74db337e837df52f6ac713/content/images/scatterblob_1.pdf -------------------------------------------------------------------------------- /content/images/scatterblob_1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SORTEE-Github-Hackathon/manuscript/8d5bc4ece59c37b94e74db337e837df52f6ac713/content/images/scatterblob_1.png -------------------------------------------------------------------------------- /content/images/twitter.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | -------------------------------------------------------------------------------- /content/manual-references.bib: -------------------------------------------------------------------------------- 1 | @misc{https://git-scm.com/book/en/v2/Getting-Started-A-Short-History-of-Git, 2 | title = {Git - {A} {Short} {History} of {Git}}, 3 | url = {https://git-scm.com/book/en/v2/Getting-Started-A-Short-History-of-Git}, 4 | urldate = {2023-03-08}, 5 | } 6 | 7 | @misc{https://happygitwithr.com, 8 | title = {Happy {Git} with {R}}, 9 | url = {https://happygitwithr.com}, 10 | urldate = {2023-03-08}, 11 | } 12 | 13 | @misc{https://ourcodingclub.github.io, 14 | title = {Our {Coding} {Club}}, 15 | url = {https://ourcodingclub.github.io}, 16 | urldate = {2023-03-08}, 17 | } 18 | 19 | @misc{https://ghdocs-prod.azurewebsites.net/en/repositories/working-with-files/managing-large-files/about-large-files-on-github, 20 | title = {About {Large} {Files} on {GitHub}}, 21 | url = {https://ghdocs-prod.azurewebsites.net/en/repositories/working-with-files/managing-large-files/about-large-files-on-github}, 22 | urldate = {2023-03-08}, 23 | } 24 | 25 | @software{10.5281/zenodo.6097109, 26 | author = {Emma Hudgins}, 27 | title = {Data and code for '{Hotspots} of pest‐induced US urban tree death, 2020–2050', published in {Journal} of {Applied} {Ecology}}, 28 | month = feb, 29 | year = 2022, 30 | publisher = {Zenodo}, 31 | version = {published}, 32 | doi = {10.5281/zenodo.6097109}, 33 | url = {https://doi.org/10.5281/zenodo.6097109} 34 | } 35 | 36 | 37 | @article{10.1111/geb.13346, 38 | author = {Sabatini, Francesco Maria and Lenoir, Jonathan and Hattab, Tarek and Arnst, Elise Aimee and Chytrý, Milan and Dengler, Jürgen and De Ruffray, Patrice and Hennekens, Stephan M. and Jandt, Ute and Jansen, Florian and Jiménez-Alfaro, Borja and Kattge, Jens and Levesley, Aurora and Pillar, Valério D. and Purschke, Oliver and Sandel, Brody and Sultana, Fahmida and Aavik, Tsipe and Aćić, Svetlana and Acosta, Alicia T. R. and Agrillo, Emiliano and Alvarez, Miguel and Apostolova, Iva and Arfin Khan, Mohammed A. S. and Arroyo, Luzmila and Attorre, Fabio and Aubin, Isabelle and Banerjee, Arindam and Bauters, Marijn and Bergeron, Yves and Bergmeier, Erwin and Biurrun, Idoia and Bjorkman, Anne D. and Bonari, Gianmaria and Bondareva, Viktoria and Brunet, Jörg and Čarni, Andraž and Casella, Laura and Cayuela, Luis and Černý, Tomáš and Chepinoga, Victor and Csiky, János and Ćušterevska, Renata and De Bie, Els and de Gasper, André Luis and De Sanctis, Michele and Dimopoulos, Panayotis and Dolezal, Jiri and Dziuba, Tetiana and El-Sheikh, Mohamed Abd El-Rouf Mousa and Enquist, Brian and Ewald, Jörg and Fazayeli, Farideh and Field, Richard and Finckh, Manfred and Gachet, Sophie and Galán-de-Mera, Antonio and Garbolino, Emmanuel and Gholizadeh, Hamid and Giorgis, Melisa and Golub, Valentin and Alsos, Inger Greve and Grytnes, John-Arvid and Guerin, Gregory Richard and Gutiérrez, Alvaro G. and Haider, Sylvia and Hatim, Mohamed Z. and Hérault, Bruno and Hinojos Mendoza, Guillermo and Hölzel, Norbert and Homeier, Jürgen and Hubau, Wannes and Indreica, Adrian and Janssen, John A. M. and Jedrzejek, Birgit and Jentsch, Anke and Jürgens, Norbert and Kącki, Zygmunt and Kapfer, Jutta and Karger, Dirk Nikolaus and Kavgacı, Ali and Kearsley, Elizabeth and Kessler, Michael and Khanina, Larisa and Killeen, Timothy and Korolyuk, Andrey and Kreft, Holger and Kühl, Hjalmar S. and Kuzemko, Anna and Landucci, Flavia and Lengyel, Attila and Lens, Frederic and Lingner, Débora Vanessa and Liu, Hongyan and Lysenko, Tatiana and Mahecha, Miguel D. and Marcenò, Corrado and Martynenko, Vasiliy and Moeslund, Jesper Erenskjold and Monteagudo Mendoza, Abel and Mucina, Ladislav and Müller, Jonas V. and Munzinger, Jérôme and Naqinezhad, Alireza and Noroozi, Jalil and Nowak, Arkadiusz and Onyshchenko, Viktor and Overbeck, Gerhard E. and Pärtel, Meelis and Pauchard, Aníbal and Peet, Robert K. and Peñuelas, Josep and Pérez-Haase, Aaron and Peterka, Tomáš and Petřík, Petr and Peyre, Gwendolyn and Phillips, Oliver L. and Prokhorov, Vadim and Rašomavičius, Valerijus and Revermann, Rasmus and Rivas-Torres, Gonzalo and Rodwell, John S. and Ruprecht, Eszter and Rūsiņa, Solvita and Samimi, Cyrus and Schmidt, Marco and Schrodt, Franziska and Shan, Hanhuai and Shirokikh, Pavel and Šibík, Jozef and Šilc, Urban and Sklenář, Petr and Škvorc, Željko and Sparrow, Ben and Sperandii, Marta Gaia and Stančić, Zvjezdana and Svenning, Jens-Christian and Tang, Zhiyao and Tang, Cindy Q. and Tsiripidis, Ioannis and Vanselow, Kim André and Vásquez Martínez, Rodolfo and Vassilev, Kiril and Vélez-Martin, Eduardo and Venanzoni, Roberto and Vibrans, Alexander Christian and Violle, Cyrille and Virtanen, Risto and von Wehrden, Henrik and Wagner, Viktoria and Walker, Donald A. and Waller, Donald M. and Wang, Hua-Feng and Wesche, Karsten and Whitfeld, Timothy J. S. and Willner, Wolfgang and Wiser, Susan K. and Wohlgemuth, Thomas and Yamalov, Sergey and Zobel, Martin and Bruelheide, Helge}, 39 | title = {sPlotOpen – An environmentally balanced, open-access, global dataset of vegetation plots}, 40 | journal = {Global Ecology and Biogeography}, 41 | volume = {30}, 42 | number = {9}, 43 | pages = {1740-1764}, 44 | keywords = {big data, biodiversity, biogeography, database, functional traits, macroecology, vascular plants, vegetation plots}, 45 | doi = {10.1111/geb.13346}, 46 | url = {https://onlinelibrary.wiley.com/doi/abs/10.1111/geb.13346}, 47 | eprint = {https://onlinelibrary-wiley-com.lib-ezproxy.concordia.ca/doi/pdf/10.1111/geb.13346}, 48 | abstract = {Abstract Motivation Assessing biodiversity status and trends in plant communities is critical for understanding, quantifying and predicting the effects of global change on ecosystems. Vegetation plots record the occurrence or abundance of all plant species co-occurring within delimited local areas. This allows species absences to be inferred, information seldom provided by existing global plant datasets. Although many vegetation plots have been recorded, most are not available to the global research community. A recent initiative, called ‘sPlot’, compiled the first global vegetation plot database, and continues to grow and curate it. The sPlot database, however, is extremely unbalanced spatially and environmentally, and is not open-access. Here, we address both these issues by (a) resampling the vegetation plots using several environmental variables as sampling strata and (b) securing permission from data holders of 105 local-to-regional datasets to openly release data. We thus present sPlotOpen, the largest open-access dataset of vegetation plots ever released. sPlotOpen can be used to explore global diversity at the plant community level, as ground truth data in remote sensing applications, or as a baseline for biodiversity monitoring. Main types of variable contained Vegetation plots (n = 95,104) recording cover or abundance of naturally co-occurring vascular plant species within delimited areas. sPlotOpen contains three partially overlapping resampled datasets (c. 50,000 plots each), to be used as replicates in global analyses. Besides geographical location, date, plot size, biome, elevation, slope, aspect, vegetation type, naturalness, coverage of various vegetation layers, and source dataset, plot-level data also include community-weighted means and variances of 18 plant functional traits from the TRY Plant Trait Database. Spatial location and grain Global, 0.01–40,000 m². Time period and grain 1888–2015, recording dates. Major taxa and level of measurement 42,677 vascular plant taxa, plot-level records. Software format Three main matrices (.csv), relationally linked.}, 49 | year = {2021} 50 | } 51 | -------------------------------------------------------------------------------- /content/manual-references.json: -------------------------------------------------------------------------------- 1 | [ 2 | { 3 | "id": "url:https://github.com/manubot/rootstock", 4 | "type": "webpage", 5 | "URL": "https://github.com/manubot/rootstock", 6 | "title": "manubot/rootstock GitHub repository", 7 | "container-title": "GitHub", 8 | "issued": { 9 | "date-parts": [ 10 | [ 11 | 2019 12 | ] 13 | ] 14 | }, 15 | "author": [ 16 | { 17 | "given": "Daniel", 18 | "family": "Himmelstein" 19 | } 20 | ] 21 | }, 22 | { 23 | "author": [ 24 | { 25 | "family": "Ushey", 26 | "given": "Kevin" 27 | } 28 | ], 29 | "genre": "Manual", 30 | "id": "ushey2022", 31 | "issued": { 32 | "date-parts": [ 33 | [ 34 | 2022 35 | ] 36 | ] 37 | }, 38 | "title": "Renv: Project environments", 39 | "title-short": "Renv", 40 | "type": "book", 41 | "URL": "https://CRAN.R-project.org/package=renv" 42 | } 43 | ] 44 | -------------------------------------------------------------------------------- /content/metadata.yaml: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Not just for programmers: How GitHub can accelerate collaborative and reproducible research in ecology and evolution" 3 | keywords: 4 | - GitHub 5 | - Reproducible research 6 | - Collaboration 7 | - Ecology and evolution 8 | lang: en-US 9 | authors: 10 | - github: pedrohbraga 11 | name: Pedro Henrique Pereira Braga 12 | initials: PHPB 13 | orcid: 0000-0002-1308-1562 14 | email: ph.pereirabraga@gmail.com 15 | twitter: pedrohp_braga 16 | mastodon: pedrobraga 17 | mastodon-server: ecoevo.social 18 | corresponding: true 19 | symbol_str: "†" 20 | affiliations: 21 | - Department of Biology, Concordia University, 7141 Sherbrooke Street West, Montreal, QC H4B 1R6, Canada 22 | - github: katherinehebert 23 | name: Katherine Hébert 24 | initials: KH 25 | orcid: 0000-0001-7866-6775 26 | email: katherine.hebert@usherbrooke.ca 27 | twitter: hebert_kat 28 | symbol_str: "††" 29 | affiliations: 30 | - Département de biologie, Université de Sherbrooke, Québec, Canada 31 | - github: emmajhudgins 32 | name: Emma J. Hudgins 33 | initials: EJH 34 | orcid: 0000-0002-8402-5111 35 | email: emma.hudgins@carleton.ca 36 | symbol_str: "††" 37 | affiliations: 38 | - Department of Biology, Carleton University, Ottawa, ON K1S 5B6, Canada 39 | - github: Aariq 40 | name: Eric R. Scott 41 | initials: ERS 42 | orcid: 0000-0002-7430-7879 43 | email: scottericr@gmail.com 44 | symbol_str: "††" 45 | affiliations: 46 | - Communications & Cyber Techologies, University of Arizona, Tucson, USA 47 | - github: BrandonEdwards 48 | name: Brandon P.M. Edwards 49 | initials: BPME 50 | orcid: 0000-0003-0865-3076 51 | email: brandonedwards3@cmail.carleton.ca 52 | symbol_str: "††" 53 | affiliations: 54 | - Department of Biology, Carleton University, Ottawa, ON K1S 5B6, Canada 55 | - github: LunaSare 56 | name: Luna L. Sánchez Reyes 57 | initials: LLSR 58 | orcid: 0000-0001-7668-2528 59 | email: sanchez.reyes.luna@gmail.com 60 | twitter: LunaSare 61 | symbol_str: "††" 62 | affiliations: 63 | - School of Natural Sciences, University of California, Merced, USA 64 | - github: DrMattG 65 | name: Matthew J. Grainger 66 | initials: MJG 67 | orcid: 0000-0001-8426-6495 68 | email: matthew.grainger@nina.no 69 | twitter: Ed_pheasant 70 | affiliations: 71 | - Terrestrial Biodiversity, Norwegian Institute for Nature Research - NINA, Postbox 5685 Torgarden, 7485 Trondheim, Norway 72 | - github: vjf2 73 | name: Vivienne Foroughirad 74 | initials: VF 75 | orcid: 0000-0002-8656-7440 76 | email: vjf5@georgetown.edu 77 | twitter: vforoughirad 78 | affiliations: 79 | - Department of Biology, Georgetown University, Washington, DC, USA 80 | - github: fhillemann 81 | name: Friederike Hillemann 82 | initials: FH 83 | orcid: 0000-0002-8992-0676 84 | email: f.hillemann@web.de 85 | affiliations: 86 | - Department of Human Behavior, Ecology and Culture, Max Planck Institute for Evolutionary Anthropology, Leipzig, Germany 87 | - github: adbinley 88 | name: Allison D. Binley 89 | initials: ADB 90 | orcid: 0000-0001-8790-9935 91 | email: allisonbinley@cmail.carleton.ca 92 | twitter: AllisonBinley 93 | affiliations: 94 | - Department of Biology, Carleton University, Ottawa, ON K1S 5B6, Canada 95 | - github: colebrookson 96 | name: Cole B. Brookson 97 | initials: CBB 98 | orcid: 0000-0003-1237-4096 99 | email: cole.brookson@gmail.com 100 | affiliations: 101 | - Department of Biological Sciences, University of Alberta, Edmonton, AB, Canada 102 | - github: kaitlyngaynor 103 | name: Kaitlyn M. Gaynor 104 | initials: KMG 105 | orcid: 0000-0002-5747-0543 106 | email: gaynor@zoology.ubc.ca 107 | twitter: kaitlyngaynor 108 | affiliations: 109 | - Departments of Zoology and Botany, University of British Columbia, Vancouver, BC, Canada 110 | - github: shafieisabets 111 | name: Saeed Shafiei Sabet 112 | initials: SSHS 113 | orcid: 0000-0001-5919-2527 114 | email: s.shafiei.sabet@guilan.ac.ir 115 | twitter: SaeedSHSABET 116 | affiliations: 117 | - Fisheries Department, Faculty of Natural Resources, University of Guilan, Sowmeh Sara, Iran 118 | - github: Aguncan 119 | name: Ali Güncan 120 | initials: AG 121 | orcid: 0000-0003-1765-648X 122 | email: guncan.ali@gmail.com 123 | twitter: aliguncan 124 | affiliations: 125 | - Department of Plant Protection, Faculty of Agriculture, Ordu University, 52200, Ordu, Turkey 126 | - github: helenweierbach 127 | name: Helen Weierbach 128 | initials: HW 129 | orcid: 0000-0001-6348-9120 130 | email: hweierbach@lbl.gov 131 | twitter: HWeierbach 132 | affiliations: 133 | - Earth and Environmental Sciences Area, Lawrence Berkeley National Laboratory, Berkeley, CA 94720, USA 134 | - github: dylangomes 135 | name: Dylan G. E. Gomes 136 | initials: DGEG 137 | orcid: 0000-0002-2642-3728 138 | email: dylan.ge.gomes@gmail.com 139 | affiliations: 140 | - (Current) National Academy of Sciences NRC Research Associateship Program, Northwest Fisheries Science Center, National Marine Fisheries Service, National Oceanic and Atmospheric Administration, Seattle, WA, USA 98112 141 | - (Former) Cooperative Institute for Marine Resources Studies, Hatfield Marine Science Center, Oregon State University, Newport, OR, USA 97365 142 | - github: robcrystalornelas 143 | name: Robert Crystal-Ornelas 144 | initials: RCO 145 | orcid: 0000-0002-6339-1139 146 | email: rcrystalornelas@lbl.gov 147 | twitter: rob_c_ornelas 148 | symbol_str: "†" 149 | affiliations: 150 | - Earth and Environmental Sciences Area, Lawrence Berkeley National Laboratory, Berkeley, CA 94720, USA -------------------------------------------------------------------------------- /data/cognitive_load_table.csv: -------------------------------------------------------------------------------- 1 | Knowledge/tools required ☞ Ways to use GitHub ↓ ,Creating a remote and local GitHub repository,"A markup language (e.g., markdown)",git add/commit/push/pull,GitHub Pages,Releases,git branch/ pull requests,Solving conflicts and merging,Forking,GitHub Actions,Creating and solving issues,Creating and participating in discussions,GitHub gists,Cognitive Load 2 | Storing a research compendium,1,0,1,0,0,0,,,,,,,2 3 | Virtual lab notebook,1,1,1,0,0,1,1,,,,,,5 4 | Educational materials,1,1,1,1,1,0,0,,,,,,5 5 | Project management,1,1,0,0,0,0,0,0,,1,1,,4 6 | Academic Websites,1,1,1,1,0,0,0,1,,,,,5 7 | Archiving citeable code and data,1,0,1,0,0,0,0,0,0,,,,2 8 | Asynchronous collaborative coding and writing,1,1,1,0,0,1,1,1,1,1,1,,9 9 | Writing a manuscript,1,1,1,0,0,1,0,0,1,,,,5 10 | Peer-reviews,1,1,1,0,0,0,1,0,0,1,1,,6 11 | Open scientific discussions,1,1,1,,,0,,,,,,1,4 12 | Project continuity,1,1,1,,,1,,,,,,,4 13 | GitHub Organizations,1,1,1,,1,1,,,,,,,5 14 | Automation,1,1,1,,,1,1,1,1,1,1,,7 -------------------------------------------------------------------------------- /data/collaborator_roles.csv: -------------------------------------------------------------------------------- 1 | Role,Description,GitHub Feature,Use Case 2 | Project manager,"Owns the GitHub repository for a project, and leads the academic project (e.g., lead author of a manuscript).",Issue,Assign tasks to collaborators 3 | ,,README,"Project descritption, citation, DOIs" 4 | ,,GitHub repository,"Set contributor permissions, share code of conduct" 5 | ,,Discussion,Discuss project directions and goals 6 | ,,Pull Request,Approve and incorporate edits to code and/or writing 7 | ,,Release,Trigger archival of code and data and DOI assignment 8 | ,,GitHub Pages,"Share up-to-date reports, figures, or draft manuscript" 9 | Co-author,"Contributes to writing and other aspects of research, but may have limited or no experience with programming, git, and/or GitHub.",Discussion,Discuss proposed changes to manuscript 10 | ,,Issue,"Propose changes involving code (e.g. analyses, figures)" 11 | ,,GitHub repository,Edit Markdown text or add files 12 | Code contributor,Contributes code to the project (may also contribute to writing and other aspects of research).,Pull Request,"Contribute changes to code, initiate code review" 13 | ,,GitHub Pages,Contribute to project website 14 | ,,Issue,Suggest code changes 15 | Code reviewer,"Reviews project code (e.g. a co-author or a peer-reviewer). They are familiar with coding, but not necessarily with git or GitHub (but they are willing to learn).",Issue,Highlight specific lines of code and make suggestions 16 | ,,Pull Request,Review or recommended changes in code 17 | ,,GitHub repository,Find all code related to a project 18 | Community,"Not involved in the project directly, but wishes to use or adapt data or code for their own analysis.",Fork,"Create a linked, editable copy of the repository" 19 | ,,Discussion,Ask questions about data and code 20 | ,,GitHub Pages,View project website 21 | ,,Issue,Suggest additional features and report bugs -------------------------------------------------------------------------------- /data/comparison_table_raw.csv: -------------------------------------------------------------------------------- 1 | Guild,Software,Version control,Cloud-storage backup,Passive collaboration,Active real-time collaboration,Does it provide a reasonably unrestrictive free version?,Is it permanent (e.g. through a DOI)?,Storage limits,GitHub Integration 2 | Multi-tool,GitHub,Yes,Yes,Yes,No,Broadly used free version. Advanced features are provided for free to students and education professionals.,"A DOI can only be obtained when integrating to other services that can mint a DOI (e.g., Zenodo, OSF).","100 MB per file, 500 MB per private repository (2 GB for paid accounts). 100 GB for public repositories. Larger files (up to 2 GB) can be attached to releases.",Not applicable. 3 | Multi-tool,Open Science Framework,Yes,Yes,Yes,Yes,Yes.,Yes,"25 GB for private projects, up to 5 GB per file, plus partner add-ons, 50 GB for public projects",Yes 4 | Long-term (public) data repositories,PANGAEA,Yes,Yes,Yes,No,Yes.,Yes,10 GB free,No 5 | Long-term (public) data repositories,Zenodo,After published,After published,Yes,No,Yes.,Yes,50 GB per dataset,Yes 6 | Long-term (public) data repositories,Dryad,After published,After published,Yes,No,"No, however certain journals cover costs.",Yes,300 GB per publication,No. 7 | Long-term (public) data repositories,Figshare,Yes,Yes,Yes,No,Yes.,Yes,"20 GB free, up to 5 TB",Yes 8 | Temporary (personal) drive storage,Google Drive,Yes,Yes,Yes,Yes,Free version is restrictive.,No,"15GB free, up to 100GB with Google One",Yes 9 | Temporary (personal) drive storage,Box,Limited,Yes,Yes,Yes,No.,No,UnLimited total size for subscription,Yes 10 | Temporary (personal) drive storage,DropBox,Limited,Yes,Yes,Yes,Free version is restrictive.,No,2 GB free,Yes 11 | Temporary (personal) drive storage,OneDrive and the Office Suite,Yes,Yes,Yes,Yes,Free version is restrictive.,No,"5 GB free, up to 1TB paid",Yes 12 | Collaborative code and text editors,Overleaf (online latex editor),Yes,Yes,Yes,Yes,Free version is restrictive. Only affiliated institutions (majority from the Global North) obtain premium access.,No,"1 MB for individual LaTeX files, 50MB for individual files, unlimited project size.",Yes 13 | Collaborative code and text editors,Jupyter Notebook,Yes,Yes,Yes,With Colab,Yes.,No,"via Binder: no hard limit, but suggests no files >100MB, can also store on GitHub or Google Colab",Yes 14 | Collaborative code and text editors,HackMD,Yes,Yes,Yes,Yes,Free version is moderatively restrictive.,No,"3 documents free, private invitee limits",Yes 15 | Collaborative code and text editors,Colaboratory,Yes,Yes,Yes,Yes,"Free version is moderatively unresitrcitve, unless high computational resources are required.",No,Colab that is free of charge notebooks can run for at most 12 hours. File storage is bounded to Google Drive's limitations. 12 GB GPU RAM .,No. 16 | -------------------------------------------------------------------------------- /data/scatterblob_data_raw.csv: -------------------------------------------------------------------------------- 1 | Ways to use GitHub,Alternative title,Cognitive load - real,Cognitive load - sequential,Cognitive load - real - non-overlapping,Perceived Technical difficulty,Min degree of collaboration X1,Max degree of collaboration X2,Example,, 2 | Archiving citeable code and data,Citeable data and code,2,1,2.2,1,1,4,link,, 3 | Storing a research compendium,Working diaries / blogs,2,2,2.8,1,1,4,life-list http://blog.phytools.org/ ,1 = present you and future you,1 = individual 4 | Project management,Project management (issues and discussions),4,3,4,1,2,5,"(e.g., github issues)",4 = future collaborators,4 = the community 5 | Project continuity,Project continuity,4,4,4.7,1,2,4,,4 = resolving conflicts, 6 | Open scientific discussions,Developing data standards,4,5,4.35,1,4,5,https://github.com/ess-dive-community,"3 = requires knowledge of additional languages in addition to github (e.g., R Markdown)", 7 | Virtual laboratory notebook,Lab management notebooks,5,6,5.35,4,1,4,link 1 link 2,3 = present public,3 = organization/ multiple labs 8 | Educational materials,Pedagogic material,5,7,5.7,2,1,5,Tidy Tuesday,2 = present collaborators,2 = within your own lab 9 | Academic websites,Hosting and deploying of Academic Websites,5,8,6.05,2,1,5,https://github.com/cabinetofcuriosity,5 = future public (people you do not know),5 = the general public 10 | Writing a manuscript,Reproducible manuscripts,5,9,6.4,5,2,4,https://github.com/PoisotLab/manuscript-template,Technical difficulty, 11 | Organizing and managing teams,Organizing and managing teams,5,10,6.75,3,2,5,https://github.com/SORTEE-Github-Hackathon,, 12 | Peer-reviews,Peer-reviews,6,11,8.4,2,1,3,link,2 = some push/pull/forking required, 13 | Asynchronous collaborative coding and writing,Asynchronous collaborative coding and writing,9,12,9.3,4,4,5,,, 14 | Automation,Automation of workflows,7,13,9.8,5,1,5,link,5= more complex GitHub tools like actions, 15 | -------------------------------------------------------------------------------- /editorial-communication/.gitignore: -------------------------------------------------------------------------------- 1 | /.quarto/ 2 | -------------------------------------------------------------------------------- /editorial-communication/.quarto/xref/90dd3357: -------------------------------------------------------------------------------- 1 | {"entries":[{"order":{"number":4,"section":[0,0,1,0,4,0,0]},"key":"sec-E1.3","caption":"E1.3. Another reason that many EEBers don’t use GitHub appears to be related to how we develop code for projects. Unless we are developing packages that others are likely to use, we tend to develop one-off scripts or functions that, once they work and are run, are never returned to. Version control is not used widely, or even needed in these cases (and my own work in software engineering provenance software has similarly had little uptake for the same reasons). I recognize that this makes it difficult to document the processes involved, but if the goal is simply to analyze the data at hand and push out another paper, why deal with the overhead of version control? At root, this is a sociological phenomenon, not a scientific one. Within your ms., consider saying something about how even one-off scripts may need to be documented, archived, and assigned a DOI to conform to evolving archiving requirements of journals."},{"order":{"number":10,"section":[0,0,2,0,4,0,0]},"key":"sec-R1.3","caption":"R1.3. Although the abstract states ‘We outline features ranging from low to high technical difficulty’ the paper reads a bit like a laundry list of what GitHub can do (in fact, the word ‘can’ is used about 140 times, which makes for tedious read). Figure 2 helps sort through this laundry list and defines the technical difficulty. It might be better to clearly lay out where anybody can start using GitHub effectively in the text. And the emphasis is on ‘effectively’. Most people are not likely to learn a new piece of software if it does not promise to reduce effort and time. So, defining tasks where GitHub shines in terms of return on investment maybe the better approach to convincing new users and then only mention the advance use cases with some pointers to further reading, but not going into too much detail."},{"order":{"number":8,"section":[0,0,2,0,2,0,0]},"key":"sec-R1.1","caption":"R1.1. I would, however, recommend some restructuring and shortening. As it stands, this paper is too long and some of the use cases are too nerdy to spark enthusiasm in somebody who is not already using GitHub. Breaking it into 13 use cases leads to some repetition and those use cases may be combined more effectively for convincing a new user."},{"order":{"number":6,"section":[0,0,1,1,1,0,0]},"key":"sec-E1.5","caption":"E1.5. Finally, DropBox, SharePoint, and OneDrive are file-sharing systems that include version control, are widely supported, especially in colleges and universities, and are much easier to use for those who might be uncomfortable learning a system such as GitHub. Other than the ability to clone and fork, why should one choose GitHub over, for example, DropBox or SharePoint? More should be made of this in text, as opposed to burying it in Table 1, which is referenced only once in text (line 232) and only in the context of other longterm archives (line 231). Indeed, I suggest a somewhat expanded section of the ms. dedicated to a detailed exploration of the comparisons made in this Table. Otherwise, the ms. comes across as more proselytizing and less analytical/convincing."},{"order":{"number":15,"section":[0,1,0,0,4,0,0]},"key":"sec-R2.3","caption":"R2.3. I would find it helpful to give a brief (1-2 sentence) history of Git (L85-89). Namely, that it was developed as an aid for software development within distributed groups of software engineers and was developed within an open-source framework so that it could be improved by the community. This provides more context as to why Github (as it extends Git) is a useful tool for collaboration “by design”."},{"order":{"number":3,"section":[0,0,1,0,3,0,0]},"key":"sec-E1.2","caption":"E1.2. In my own experience, the “public” nature of repos is a major barrier to the use of GitHub for exactly the reason you suggest - EEB practioners remain very uncomfortable with sharing data pre-publication (and often even post-publication). Some additional emphasis on the ability to make repos “private” should be included beyond the Boxes."},{"order":{"number":9,"section":[0,0,2,0,3,0,0]},"key":"sec-R1.2","caption":"R1.2. The title and abstract gave me the impression that the goal is to convince EEB researcher to start using GitHub. If that’s the case, it might be better to tailor the use cases to that entry level and use less GitHub specific lingo. Advanced usage may be mentioned but not detailed as much as it is currently done. E.g. collaboratively writing a paper in GitHub is probably out of the question for most. Most GitHub options for communication, discussion, issue tracking are still somewhat esoteric for most non-programmers."},{"order":{"number":5,"section":[0,0,1,1,0,0,0]},"key":"sec-E1.4","caption":"E1.4. I am surprised you didn’t include integration between GitHub and Overleaf. Overleaf is also a good collaborative latex-based text processor, and provides syncing with GitHub (and Dropbox) in a way that will be more familiar to beginning users. (Actually, I eventually found it buried in Table 1)"},{"order":{"number":1,"section":[0,0,1,0,0,0,0]},"key":"sec-E1","caption":"Comments from the Editor (E1)"},{"order":{"number":14,"section":[0,1,0,0,3,0,0]},"key":"sec-R2.2","caption":"R2.2. Figure 2 was useful, especially as it summarized across multiple areas that a reader make in-roads into using Github. Please clarify how the “Technical Difficulty” was assessed. Was this based on the impression of the working group? Was it quantified using different types of required knowledge (e.g., programming, software design, working in the Terminal, etc.)?"},{"order":{"number":2,"section":[0,0,1,0,2,0,0]},"key":"sec-E1.1","caption":"E1.1. I agree with Reviewer 1 that these could be streamlined somewhat into a smaller number of more generalizable cases. They also are a bit heavily weighted towards more experienced users. “Simple” operations like push, pull, and commit are rarely understandable to new users, who routinely forget to commit their actions. The GitHub Desktop app makes many of the operations and use of GitHub somewhat easier, and is a good entree into GitHub and Git for novices. More could be made of the desktop app."},{"order":{"number":16,"section":[0,1,0,0,5,0,0]},"key":"sec-R2.4","caption":"R2.4. I suggest adding a discussion on dependency testing within or following the paragraph on Automation (Lines 373-382). This is a project “ecosystem” phenomenon that comes from collaboration, where you build your project on the work of someone else. As projects change over time, they can alter other projects. Software engineers have been working on this challenge for a long time in distributed teams where different parts of software are being built by different programmers. Checks can be done automatically within the software engineering framework (see Pasquier et al. 2017 https://www.nature.com/articles/sdata2017114). Beyond detection, any major changes can be detected and presented without additional work from the user via features like badges (https://shields.io/) within the project page (e.g., README)."},{"order":{"number":17,"section":[0,1,0,0,6,0,0]},"key":"sec-R2.5","caption":"R2.5. Related to Major Comments 1 and 4, given that the focus of the paper is toward integration into EEB scientific research workflows, I suggest adding another figure (or replacing Figure 1) that details a generalized scientific research workflow (e.g., Munafò et al. 2017 https://www.nature.com/articles/s41562-016-0021) and how Github supports/augments that workflow. This could relate to or build on Table 2, which a useful summarization of important features as they relate to different research participants."},{"order":{"number":7,"section":[0,0,2,0,0,0,0]},"key":"sec-R1","caption":"Recommendations from Reviewer 1 (R1)"},{"order":{"number":13,"section":[0,1,0,0,2,0,0]},"key":"sec-R2.1","caption":"R2.1. Figure 1 was more confusing to me than helpful. It presents a view of a Github interface in order to detail generalized features; however, it is edited/abstracted so much that it doesn’t map easily to the interface as it would be viewed by a reader of the paper. To improve this I would reduce the level of abstraction of the web interface."},{"order":{"number":12,"section":[0,1,0,0,0,0,0]},"key":"sec-R2","caption":"Recommendations from Reviewer 2 (R2)"},{"order":{"number":11,"section":[0,0,2,0,5,0,0]},"key":"sec-R1.4","caption":"R1.4. In my experience, the project continuity is actually very high on the importance list for researchers, i.e., knowing that the code and data will be findable by the next student. This includes the discussion of organizing and managing teams, keeping lab information in one place etc. Followed by code versioning and the ability to go back to older versions. Interest in website development is picking up because it really is simple to do in GitHub, and the information can be maintained by several people (i.e., a lab group)."}],"headings":["sec-E1","as-a-long-term-but-sporadic-github-user-myself-i-agree-with-most-of-the-points-and-cases-presented-in-the-paper.","sec-E1.1","sec-E1.2","sec-E1.3","sec-E1.4","sec-E1.5","sec-R1","this-paper-clearly-communicates-the-enthusiasm-of-the-authors-for-integrating-github-in-the-eeb-research-process.-advantages-in-areas-of-collaboration-transparent-and-reproducible-science-are-clear-and-nicely-discussed.-this-is-a-well-written-paper.","sec-R1.1","sec-R1.2","sec-R1.3","sec-R1.4","r1.5.-line-346-delete-second-can-who-can-also-can-change-through-time","r1.6.-line-389-it-should-be-each-others-work-contribute-to-each-other-work-without-necessarily","r1.7.-line-457-missing-collaborator-especially-when-many-may-be","r1.8.-line-477-not-sure-what-this-sentence-is-saying-requiring-the-complementation-of-other-tools-to-fully-integration-project-files-and-github-repositories","sec-R2","the-manuscript-presents-how-ecologists-and-evolutionary-biologists-eeb-can-use-collaborative-software-development-project-management-tools.-the-authors-present-a-high-level-view-of-github-and-the-git-version-control-system-that-is-at-its-core.-as-the-authors-detail-the-tools-that-github-provides-has-broad-potential-to-be-leveraged-within-the-eeb-community.-the-paper-is-well-written-and-helps-to-make-github-tools-and-related-concepts-legible-to-eeb-audiences.-on-the-whole-i-see-this-as-potentially-being-an-impactful-paper-for-improving-eeb-research.-i-have-the-following-major-and-minor-comments-for-the-authors","sec-R2.1","sec-R2.2","sec-R2.3","sec-R2.4","sec-R2.5","r2.6.-the-sentence-from-line-66-67-is-missing-a-close-parenthesis.","r2.7.-there-appears-to-be-a-fourth-barrier-at-line-478.-i-suggest-splitting-the-paragraph-from-line-472-to-483-into-two-paragraphs-and-expanding-on-both-reluctance-to-share-data-and-language-specific-resources-as-barriers-to-adoption.","r2.8.-line-570-could-also-be-e-should-be-could-also-be-a."]} -------------------------------------------------------------------------------- /editorial-communication/.quarto/xref/INDEX: -------------------------------------------------------------------------------- 1 | { 2 | "response-to-the-reviewers.Qmd": { 3 | "response-to-the-reviewers.html": "90dd3357", 4 | "response-to-the-reviewers.tex": "84ef80fd" 5 | } 6 | } -------------------------------------------------------------------------------- /editorial-communication/_quarto.yml: -------------------------------------------------------------------------------- 1 | project: 2 | output-dir: . 3 | 4 | format: 5 | docx: default 6 | html: default -------------------------------------------------------------------------------- /editorial-communication/cover-letter-submission.Qmd: -------------------------------------------------------------------------------- 1 | --- 2 | title: Letter to the Editor 3 | subtitle: "Not just for programmers: How GitHub can accelerate collaborative and reproducible research in ecology and evolution" 4 | date: today 5 | date-format: long 6 | format: 7 | html: 8 | theme: cosmo 9 | highlight-style: tango 10 | embed-resources: true 11 | --- 12 | 13 | Dear Editor, 14 | 15 | We would like to submit our manuscript entitled “Not just for programmers: How GitHub can accelerate collaborative and reproducible research in ecology and evolution” for consideration to be published in *Methods in Ecology and Evolution*. 16 | Our study provides researchers with a critical review of thirteen practical ways they can use GitHub – an online, cloud-based service for cooperative and documented code development – to make their research more collaborative, transparent, and reproducible. 17 | 18 | Most scientists, including researchers in ecology and evolutionary biology, have become critically dependent on computational tools in their research. 19 | This code-dependent workflow imposes steep requirements towards an efficient, well-documented process in the publication and collaboration of maintainable scientific code. 20 | Albeit, many researchers lack exposure to adequate software development practices and thus are required to dedicate valuable time and effort to learning how to use research-facilitating tools. 21 | Formal academic courses on these types of tools are often unavailable and researchers are left to learn through informal blogs, videos, and other online forums. 22 | This may present a plethora of practical barriers to applying adequate standards to maintaining scientific code. 23 | 24 | The adoption of GitHub in ecology and evolutionary biology workflows is not widespread in part because there have been only a few disparate attempts at creating domain-specific information and guidelines. 25 | In our study, we review and discuss one of the most used web-based platforms for computational version control and collaboration, GitHub, and provide researchers in ecology and evolution with comprehensive and practical workflows aimed at facilitating their scientific code and management process. 26 | 27 | Our manuscript is the most accessible and practical guide to using GitHub in ecology and evolution research to date. 28 | We build upon our own experiences (as an international collaboration from authors across many ecology and evolution subdisciplines) and on existing resources mainly targeted at other disciplines, to highlight how researchers can use the readily available GitHub suite to make their research practices reproducible, collaborative, and transparent. 29 | Our manuscript is important for the *Methods in Ecology and Evolution* readership because researchers in ecology and evolutionary biology can greatly benefit from our perspectives to migrate and incorporate GitHub workflows in their research practices ultimately towards an open and collaborative science. 30 | Our manuscript also complements recently published literature outlining how the ongoing adoption of Open Science practices is transforming research in ecology and evolutionary biology. 31 | 32 | The enclosed manuscript is available as a preprint on the MetaArXiv server (https://www.doi.org/10.31222/osf.io/x3p2q), with over 440 downloads and 2,400 views in four months. 33 | We declare that our study is not published or under consideration for publication elsewhere. 34 | 35 | All authors have contributed and reviewed the current version of the manuscript and agreed to its submission to Methods in Ecology and Evolution. 36 | 37 | We appreciate your time and consideration of our manuscript for publication in your journal. 38 | 39 | Sincerely, 40 | 41 | Pedro Henrique Pereira Braga, on behalf of all co-authors 42 | 43 | --- 44 | 45 | We would like to suggest the following potential reviewers for our manuscript: 46 | - 47 | - 48 | - 49 | -------------------------------------------------------------------------------- /editorial-communication/custom.scss: -------------------------------------------------------------------------------- 1 | /*-- scss:defaults --*/ 2 | 3 | 4 | /*-- scss:rules --*/ 5 | 6 | .response { 7 | width: 85% !important; 8 | margin-left: auto; 9 | margin-right: auto; 10 | } -------------------------------------------------------------------------------- /editorial-communication/editorial-communication.Rproj: -------------------------------------------------------------------------------- 1 | Version: 1.0 2 | 3 | RestoreWorkspace: Default 4 | SaveWorkspace: Default 5 | AlwaysSaveHistory: Default 6 | 7 | EnableCodeIndexing: Yes 8 | UseSpacesForTab: Yes 9 | NumSpacesForTab: 2 10 | Encoding: UTF-8 11 | 12 | RnwWeave: Sweave 13 | LaTeX: pdfLaTeX 14 | -------------------------------------------------------------------------------- /editorial-communication/response-template.docx: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SORTEE-Github-Hackathon/manuscript/8d5bc4ece59c37b94e74db337e837df52f6ac713/editorial-communication/response-template.docx -------------------------------------------------------------------------------- /editorial-communication/response-to-the-reviewers.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SORTEE-Github-Hackathon/manuscript/8d5bc4ece59c37b94e74db337e837df52f6ac713/editorial-communication/response-to-the-reviewers.pdf -------------------------------------------------------------------------------- /editorial-communication/skeleton.bib: -------------------------------------------------------------------------------- 1 | @Manual{R-base, 2 | title = {R: A Language and Environment for Statistical Computing}, 3 | author = {{R Core Team}}, 4 | organization = {R Foundation for Statistical Computing}, 5 | address = {Vienna, Austria}, 6 | year = {2021}, 7 | url = {https://www.R-project.org/}, 8 | } 9 | 10 | @Manual{R-dplyr, 11 | title = {dplyr: A Grammar of Data Manipulation}, 12 | author = {Hadley Wickham and Romain François and Lionel Henry and Kirill Müller}, 13 | year = {2022}, 14 | note = {R package version 1.0.8}, 15 | url = {https://CRAN.R-project.org/package=dplyr}, 16 | } 17 | 18 | @Manual{R-forcats, 19 | title = {forcats: Tools for Working with Categorical Variables (Factors)}, 20 | author = {Hadley Wickham}, 21 | year = {2021}, 22 | note = {R package version 0.5.1}, 23 | url = {https://CRAN.R-project.org/package=forcats}, 24 | } 25 | 26 | @Manual{R-ggplot2, 27 | title = {ggplot2: Create Elegant Data Visualisations Using the Grammar of Graphics}, 28 | author = {Hadley Wickham and Winston Chang and Lionel Henry and Thomas Lin Pedersen and Kohske Takahashi and Claus Wilke and Kara Woo and Hiroaki Yutani and Dewey Dunnington}, 29 | year = {2021}, 30 | note = {R package version 3.3.5}, 31 | url = {https://CRAN.R-project.org/package=ggplot2}, 32 | } 33 | 34 | @Manual{R-hrbrthemes, 35 | title = {hrbrthemes: Additional Themes, Theme Components and Utilities for ggplot2}, 36 | author = {Bob Rudis}, 37 | year = {2020}, 38 | note = {R package version 0.8.0}, 39 | url = {http://github.com/hrbrmstr/hrbrthemes}, 40 | } 41 | 42 | @Manual{R-purrr, 43 | title = {purrr: Functional Programming Tools}, 44 | author = {Lionel Henry and Hadley Wickham}, 45 | year = {2020}, 46 | note = {R package version 0.3.4}, 47 | url = {https://CRAN.R-project.org/package=purrr}, 48 | } 49 | 50 | @Manual{R-readr, 51 | title = {readr: Read Rectangular Text Data}, 52 | author = {Hadley Wickham and Jim Hester and Jennifer Bryan}, 53 | year = {2022}, 54 | note = {R package version 2.1.2}, 55 | url = {https://CRAN.R-project.org/package=readr}, 56 | } 57 | 58 | @Manual{R-stringr, 59 | title = {stringr: Simple, Consistent Wrappers for Common String Operations}, 60 | author = {Hadley Wickham}, 61 | year = {2019}, 62 | note = {R package version 1.4.0}, 63 | url = {https://CRAN.R-project.org/package=stringr}, 64 | } 65 | 66 | @Manual{R-tibble, 67 | title = {tibble: Simple Data Frames}, 68 | author = {Kirill Müller and Hadley Wickham}, 69 | year = {2021}, 70 | note = {R package version 3.1.6}, 71 | url = {https://CRAN.R-project.org/package=tibble}, 72 | } 73 | 74 | @Manual{R-tidyr, 75 | title = {tidyr: Tidy Messy Data}, 76 | author = {Hadley Wickham and Maximilian Girlich}, 77 | year = {2022}, 78 | note = {R package version 1.2.0}, 79 | url = {https://CRAN.R-project.org/package=tidyr}, 80 | } 81 | 82 | @Manual{R-tidyverse, 83 | title = {tidyverse: Easily Install and Load the Tidyverse}, 84 | author = {Hadley Wickham}, 85 | year = {2021}, 86 | note = {R package version 1.3.1}, 87 | url = {https://CRAN.R-project.org/package=tidyverse}, 88 | } 89 | 90 | @Book{ggplot22016, 91 | author = {Hadley Wickham}, 92 | title = {ggplot2: Elegant Graphics for Data Analysis}, 93 | publisher = {Springer-Verlag New York}, 94 | year = {2016}, 95 | isbn = {978-3-319-24277-4}, 96 | url = {https://ggplot2.tidyverse.org}, 97 | } 98 | 99 | @Article{tidyverse2019, 100 | title = {Welcome to the {tidyverse}}, 101 | author = {Hadley Wickham and Mara Averick and Jennifer Bryan and Winston Chang and Lucy D'Agostino McGowan and Romain François and Garrett Grolemund and Alex Hayes and Lionel Henry and Jim Hester and Max Kuhn and Thomas Lin Pedersen and Evan Miller and Stephan Milton Bache and Kirill Müller and Jeroen Ooms and David Robinson and Dana Paige Seidel and Vitalie Spinu and Kohske Takahashi and Davis Vaughan and Claus Wilke and Kara Woo and Hiroaki Yutani}, 102 | year = {2019}, 103 | journal = {Journal of Open Source Software}, 104 | volume = {4}, 105 | number = {43}, 106 | pages = {1686}, 107 | doi = {10.21105/joss.01686}, 108 | } 109 | 110 | -------------------------------------------------------------------------------- /output/README.md: -------------------------------------------------------------------------------- 1 | # Generated citation / reference files 2 | 3 | The `output` branch contains files automatically generated by the manuscript build process. 4 | It consists of the contents of the `output` directory of the `main` branch. 5 | These files are not tracked in `main`, but instead written to the `output` branch by continuous integration builds. 6 | 7 | ## Files 8 | 9 | This directory contains the following files: 10 | 11 | + [`citations.tsv`](citations.tsv) is a table of citations extracted from the manuscript and the corresponding standard citations and citation IDs. 12 | + [`manuscript.md`](manuscript.md) is a markdown document of all manuscript sections, with citation strings replaced by citation IDs. 13 | + [`references.json`](references.json) is CSL-JSON file of bibliographic item metadata ([see specification](https://github.com/citation-style-language/schema/blob/master/csl-data.json)) for all references. 14 | + [`variables.json`](variables.json) contains variables that were passed to the jinja2 templater. These variables contain those automatically generated by the manubot as well as those provided by the user via the `--template-variables-path` option. 15 | 16 | Pandoc consumes `manuscript.md` and `references.json` to create the formatted manuscript, which is exported to `manuscript.html`, `manuscript.pdf`, and optionally `manuscript.docx`. 17 | -------------------------------------------------------------------------------- /setup.bash: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | # Setup Manubot 3 | # Based on https://github.com/manubot/rootstock/blob/main/SETUP.md 4 | # This is designed to be run from the bash terminal 5 | 6 | # Stop on first error. 7 | set -e 8 | 9 | usage() { 10 | echo "Usage: $0 [--owner text] [--repo text] [--yes]" 11 | echo "Guides the user through the creation of a new Manubot repository for their manuscript." 12 | echo 13 | echo "If no options are supplied a fully interactive process is used." 14 | echo "OWNER and REPO refer to the details of your manuscript repo location:" 15 | echo "i.e. https://github.com/OWNER/REPO." 16 | echo 17 | echo "Options:" 18 | echo " -o --owner GitHub user or organisation name." 19 | echo " -r --repo Name of the repository for your new manuscript." 20 | echo " -y --yes Non-interactive mode. Continue script without asking for confirmation that the repo exists." 21 | echo " -s --ssh Use SSH to authenticate GitHub account. HTTPS is used by default." 22 | echo " Option only effective if --yes is also set, otherwise answer given in user interaction takes precedence." 23 | echo " -h --help Display usage information." 24 | 1>&2; exit 1; } 25 | 26 | # Check if to continue 27 | check(){ 28 | while true 29 | do 30 | echo "Once you have created your repo press enter to continue setup," 31 | read -r -p "or type exit to quit now: " input 32 | 33 | case $input in 34 | "") 35 | echo 36 | echo "Continuing Setup..." 37 | echo 38 | break 39 | ;; 40 | [eE][xX][iI][tT]) 41 | exit 1 42 | ;; 43 | *) 44 | echo 45 | echo "Invalid input, try again..." 46 | echo 47 | ;; 48 | esac 49 | done 50 | } 51 | 52 | # Option strings 53 | SHORT=o:r:hys 54 | LONG=owner:,repo:,help,yes,ssh 55 | 56 | YES=0 # continue when prompted 57 | AUTH=0 # used https or ssh auth 58 | 59 | # read the options 60 | OPTS=$(getopt --options $SHORT --long $LONG --name "$0" -- "$@") 61 | 62 | if [ $? != 0 ] ; then echo "Failed to parse options...exiting." >&2 ; exit 1 ; fi 63 | 64 | eval set -- "$OPTS" 65 | 66 | # extract options and their arguments into variables. 67 | while true ; do 68 | case "$1" in 69 | -o | --owner ) 70 | shift; 71 | OWNER=$1 72 | shift 73 | ;; 74 | -r | --repo ) 75 | REPO="$2" 76 | shift 2 77 | ;; 78 | -y | --yes ) 79 | YES=1 80 | shift 81 | ;; 82 | -s | --ssh ) 83 | AUTH=1; 84 | shift 85 | ;; 86 | -- ) 87 | shift 88 | break 89 | ;; 90 | -h | --help ) 91 | shift 92 | usage 93 | exit 1 94 | ;; 95 | *) 96 | echo "Internal error!" 97 | exit 1 98 | ;; 99 | esac 100 | done 101 | 102 | if [ -z "${OWNER}" ] || [ -z "${REPO}" ]; then 103 | echo "This script will take you through the setup process for Manubot." 104 | echo "First, we need to specify where to create the GitHub repo for your manuscript." 105 | echo 106 | echo "The URL will take this format: https://github.com/OWNER/REPO." 107 | echo "OWNER is your username or organisation" 108 | echo "REPO is the name of your repository" 109 | echo 110 | read -r -p "Type in the OWNER now:" input 111 | OWNER=$input 112 | read -r -p "Type in the REPO now:" input 113 | REPO=$input 114 | fi 115 | 116 | # If using interactive mode, check remote repo exists. 117 | if [[ "$YES" == '0' ]]; then 118 | while true 119 | do 120 | echo 121 | read -r -p "Have you manually created https://github.com/${OWNER}/${REPO}? [y/n] " input 122 | 123 | case $input in 124 | [yY][eE][sS]|[yY]) 125 | 126 | echo 127 | echo "Continuing Setup..." 128 | echo 129 | break 130 | ;; 131 | [nN][oO]|[nN]) 132 | echo 133 | echo "Go to https://github.com/new and create https://github.com/${OWNER}/${REPO}" 134 | echo "Note: the new repo must be completely empty or the script will fail." 135 | echo 136 | check 137 | break 138 | ;; 139 | *) 140 | echo 141 | echo "Invalid input, try again..." 142 | echo 143 | ;; 144 | esac 145 | done 146 | else 147 | echo "Setting up https://github.com/${OWNER}/${REPO}" 148 | fi 149 | 150 | # Clone manubot/rootstock 151 | echo 152 | echo "Cloning Rootstock..." 153 | echo 154 | git clone --single-branch https://github.com/manubot/rootstock.git ${REPO} 155 | cd ${REPO} 156 | 157 | echo 158 | echo "Setup tracking of remote..." 159 | 160 | # Configure remotes 161 | git remote add rootstock https://github.com/manubot/rootstock.git 162 | 163 | # Check auth method 164 | if [[ "$YES" == '0' ]]; then 165 | while true 166 | do 167 | echo 168 | read -r -p "Would you like to use SSH to authenticate your GitHub account? [y/n] " input 169 | 170 | case $input in 171 | [yY][eE][sS]|[yY]) 172 | AUTH=1 173 | break 174 | ;; 175 | [nN][oO]|[nN]) 176 | AUTH=0 177 | break 178 | ;; 179 | *) 180 | echo 181 | echo "Invalid input, try again..." 182 | echo 183 | ;; 184 | esac 185 | done 186 | fi 187 | 188 | case $AUTH in 189 | 0) 190 | echo 191 | echo "Seting origin URL using its https web address" 192 | echo 193 | git remote set-url origin https://github.com/${OWNER}/${REPO}.git 194 | ;; 195 | 1) 196 | echo 197 | echo "Seting origin URL using SSH" 198 | echo 199 | git remote set-url origin git@github.com:$OWNER/$REPO.git 200 | ;; 201 | esac 202 | 203 | git push --set-upstream origin main 204 | 205 | # To use GitHub Actions only: 206 | echo "Setup for GitHub Actions ONLY..." 207 | # remove AppVeyor config 208 | git rm .appveyor.yml 209 | # remove ci/install.sh (only used by AppVeyor) 210 | git rm ci/install.sh 211 | 212 | # Update README 213 | echo "Updating README..." 214 | # Perform substitutions 215 | sed "s/manubot\/rootstock/${OWNER}\/${REPO}/g" README.md > tmp && mv -f tmp README.md 216 | sed "s/manubot\.github\.io\/rootstock/${OWNER}\.github\.io\/${REPO}/g" README.md > tmp && mv -f tmp README.md 217 | 218 | echo "Committing rebrand..." 219 | git add --update 220 | git commit --message "Brand repo to $OWNER/$REPO" 221 | git push origin main 222 | echo 223 | echo "Setup complete" 224 | echo 225 | echo "The new repo has been created at $(pwd)" 226 | echo 227 | echo "A good first step is to modify content/metadata.yaml with the relevant information for your manuscript." 228 | echo 229 | -------------------------------------------------------------------------------- /webpage/README.md: -------------------------------------------------------------------------------- 1 | # Output directory containing the formatted manuscript 2 | 3 | The [`gh-pages`](https://github.com/$REPO_SLUG/tree/gh-pages) branch hosts the contents of this directory at . 4 | The permalink for this webpage version is . 5 | To redirect to the permalink for the latest manuscript version at anytime, use the link . 6 | 7 | ## Files 8 | 9 | This directory contains the following files, which are mostly ignored on the `main` branch: 10 | 11 | + [`index.html`](index.html) is an HTML manuscript. 12 | + [`manuscript.pdf`](manuscript.pdf) is a PDF manuscript. 13 | 14 | The `v` directory contains directories for each manuscript version. 15 | In general, a version is identified by the commit hash of the source content that created it. 16 | 17 | ### Timestamps 18 | 19 | The `*.ots` files in version directories are OpenTimestamps which can be used to verify manuscript existence at or before a given time. 20 | [OpenTimestamps](https://opentimestamps.org/) uses the Bitcoin blockchain to attest to file hash existence. 21 | The `deploy.sh` script run during continuous deployment creates the `.ots` files through its `manubot webpage` call. 22 | There is a delay before timestamps get confirmed by a Bitcoin block. 23 | Therefore, `.ots` files are initially incomplete and should be upgraded at a later time, so that they no longer rely on the availability of a calendar server to verify. 24 | The `manubot webpage` call during continuous deployment identifies files matched by `webpage/v/**/*.ots` and attempts to upgrade them. 25 | You can also manually upgrade timestamps, by running the following in the `gh-pages` branch: 26 | 27 | ```shell 28 | ots upgrade v/*/*.ots 29 | rm v/*/*.ots.bak 30 | git add v/*/*.ots 31 | ``` 32 | 33 | Verifying timestamps with the `ots verify` command requires running a local bitcoin node with JSON-RPC configured, at this time. 34 | 35 | ## Source 36 | 37 | The manuscripts in this directory were built from 38 | [`$COMMIT`](https://github.com/$REPO_SLUG/commit/$COMMIT). 39 | -------------------------------------------------------------------------------- /webpage/images: -------------------------------------------------------------------------------- 1 | v/latest/images -------------------------------------------------------------------------------- /webpage/index.html: -------------------------------------------------------------------------------- 1 | v/latest/index.html -------------------------------------------------------------------------------- /webpage/manuscript.pdf: -------------------------------------------------------------------------------- 1 | v/latest/manuscript.pdf --------------------------------------------------------------------------------