Contributing

This appendix detail how to contribute to the LoggingDiversity project.

Git

First you’ll need a local installation of Git on your machine.

Git (/ɡɪt/)^[8] is a distributed version control system^[9] that tracks changes in any set of computer files, usually used for coordinating work among programmers who are collaboratively developing source code during software development. Wikipedia

You can download and install Git from https://git-scm.com/. If you are looking for more information on Git than the one below I recommend this simple guide: https://rogerdudler.github.io/git-guide/.

GitHub

Then you’ll need an account on GitHub.

GitHub (/ˈɡɪthʌb/^[a]) is a developer platform that allows developers to create, store, manage and share their code. Wikipedia

Simply go on https://github.com/ and open an account.

Fork the repository

Then you’ll need to create a copy of the project. Project in Git are stored in repository. The repository versions follow a tree. Creating a copy is then called a fork. To do so, go on the repository page: https://github.com/Bioforest-project/DataAgr_Species . Then use the button on the top right named “Fork” to fork the repository. I recommend you don’t change the name of your copy. More help an be found here: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo.

Clone your fork

Great you have an online copy of the project on GitHub, but to work with it on your machine you’ll want a local copy. For that you will want to have a “clone” of the project online locally, and this is called a clone in GitHub too. There are different way of cloning your repository with the green button “<> Code” as explained here: https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository. If you are a windows user discovering all this process, I recommend that you use GitHub Desktop to manage GitHub on your desktop. GitHub Desktop can be found here and is pretty straightforward to use: https://desktop.github.com/. Most command that I will cite later, such as fork or clone, can be found directly inside GitHub Desktop.

R

If you don’t have it already you’ll need to install the R programming language.

R is a programming language for statistical computing and data visualization. It has been adopted in the fields of data mining, bioinformatics, and data analysis.^[8] Wikipedia

You can find it here: https://www.r-project.org/. I recommend that you use a version above 4.0.0.

Rstudio

Similarly, of you don’t have it already, I recommend that you use R in the RStudio integrated development environment (IDE), besides other IDE such as Visual Code Studio can be used too.

RStudio is an integrated development environment for R, a programming language for statistical computing and graphics. Wikipedia

You can find RStudio here: https://posit.co/products/open-source/rstudio/.

renv

Once R and Rstudio installed, you can launch Rstudio and install the renv library to manage all needed library for the project. Indeed the project is built using renv to improve reproducibility and collaborative work.

The renv package helps you create reproducible environments for your R projects. https://rstudio.github.io/renv/articles/renv.html

To do so you can type in a terminal:

install.pacakges("renv")

Use the repository

Great! Now you are all set-up to work with the project. For that go in your project folder LoggingDiversity/ (there is a short-cut to open the folder in GitHub Desktop). Then you can open it by double clicking the RStudio project file called LoggingDiversity.Rmd.

First you need to install all the packages with renv using:

renv::restore()

It can be a bit long the first time because it’s setting up the whole environment but will be faster the next time.

Then as described in the README, you can use the scripts in data/ to generate the data needed to run the project (for the moment only dummy data are available, and data access should be improved later).

Then you can have a look, modify, or edit text of the analyses. All the analyses are done in the Quarto documents file.qmd. Quarto are reproducible documents that mix text and code and that are the basis of the online pages that you are reading right now. More information on Quarto can be found here: https://quarto.org/.

Once you are in a Quarto file, for instance this page corresponds to 98_contributing.qmd, you can add text directly in the document and add R code in the form of chunks using CTRL+ALT+I, or the insert menu for executable cell, or the top right green button in RStudio. You can run the small chunk of code with the green arrow or with CTRL+ENTER as in any R script. To see the resulting document you can use the “Render” button in Rstudio or CTRL+SHIFT+K. Once you’ve finished updating the pages of different documents you can regenerate the whole numerical book in the “Build” panel with the “Render Book” button or CTRL+SHIFT+B.

A description of lintr and styler packages should be added if we decide to keep it.

Commit

Once you have done modifications that you want to save you can “commit” using Git. It means that you create a new version of your project. For that you can use either GitHub Desktop or the “Git” panel in Rstudio.

For Rstudio, in the “Git” panel, check the box of all files for which you want to save informations (but you may ignore some for later). The click on commit. In the pop-up window, add a commit message and click on commit to create a new version.

Congrats! You contributed locally to the project and created a new version tracked by Git.

Push

Now that you have a new version locally, or several, you may want to save them online. This is called “push” in Git, because you are pushing your local clone to your online repository or “remote” in Git. To do so you can either use GitHub Desktop or the “Git” panel in Rstudio. For Rstudio, in the “Git” panel, use the “Push” green arrow. Then have a look to your online repository, you should have all your changes available online.

Pull request

Great, no you have contributed to the project on your machine and saved a copy online on GitHub. However, you don’t have actually contributed to the original project yet. To do so you need to ask to send your changes to the main project/repository for us to review them and merge them. In Git/GitHub this is called a “Pull Request” because you are requesting that we pull your code into ours. To do so simply follow this guide: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request. Once your pull request is submitted let us handle it. It will open a dialogue page where we can exchange about your modification. We will discuss it with you, and if we all agree your contribution will be merged into the main repository and you will be listed as a project contributor, kudos!

Synchronize fork

Last but not least, if you’ve followed until here, you might have a question: “but what happens if you make changes to the project while I make changes myself?”. Don’t worry Git and GitHub are made for that. At some points if you see that we have made major changes to the project on the main repository and you want to have them back in your fork online and your clone locally you can “Synchronize your fork”: https://docs.github.com/fr/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork.

Help

If you need help to contribute please preferentially create an issue on GitHub: https://github.com/Bioforest-project/environment/issues. You may however reach us by mail with people from the core group.

Contributing to this page

This help pages is a test and a work in progress. I’ll try to expand it following help demands in issues. However, if you have any tips or resources that you got while following it, don’t hesitate to add it to the document for the users and next readers.

Have a nice testing, writing or coding 😉,

Sylvain