Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
173 lines (112 loc) · 10.3 KB

CONTRIBUTING.md

File metadata and controls

173 lines (112 loc) · 10.3 KB

Contributing

When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the owners of this repository before making a change.

📄 The Basics

📃 Building the documentation locally

If you just want to make minor edits to the text in the documentation, you don't need to go to the trouble of setting up your environment. You can just edit the files in the docs/ folder and commit+push your changes.

You will just need to have Quarto installed. To install Quarto, follow the instructions on the Quarto website. Ideally, use VSCode with the Quarto extension for a better experience.

After cloning the repository, cd to docs/ and run quarto preview . --render all --no-browser to render the documentation locally.

💡 If you want to change something in the structure of the documentation (say, the location of a menu or how the pages are laid out) take a look at the YAML file docs/_quarto.yml.

✋ How to contribute

If you want to propose changes to the documentation if you were tasked to do something, you should follow the steps below:

  1. Set up your environment by following the instructions in the Dev Setup section.
  2. Create a new branch from develop and give it a meaningful name. Best practices involve using the following format: <your-username>/<issue-number>-<short-description>. For example, if you are working on issue #3, you could name your branch jonjoncardoso/3-fix-numpy-bug.
  3. Make your changes and commit them to your branch. Remember to commit often and to write meaningful commit messages. If you are working on a specific issue, you can use the following format: #<issue-number> <commit-message>. For example, if you are working on issue #3, you could write #3 Fix numpy bug.
  4. When you are done, push all your commits and then open a pull request to merge your branch into develop. You can do this by clicking on the "Compare & pull request" button on GitHub. Make sure to add a meaningful title and description to your pull request. If you are working on a specific issue, you can use the following format: #<issue-number> <pull-request-title>. For example, if you are working on issue #3, you could write #3 Fix Numpy Bug.

🔀 Our Git branches

This repository has the following main branches:

  • main: This is the "production" branch. It contains the latest version of the website. This branch is protected and only administrators can push to it. Whatever is in here, will be rendered and published on the website.
  • develop: This is the "development" branch. It contains the latest version of the website under development.
    • This branch is not protected and anyone with access to this repository can push to it.
    • This is the branch you should be referring to when you want to make changes to the website. We might have updates to the website that are not yet ready to be published. In that case, we will push to develop and then an administrator will merge to main when we are ready to publish.
  • gh-pages: This is the branch that contains the rendered version of the website. This branch is automatically updated by the GitHub workflow. Do not push to this branch.

However, you should not be working directly on develop. Instead, you should create a new branch from develop and work on that branch. When you are done, you should open a pull request to merge your branch into develop. This way, we can review your changes before merging them into develop. This is a good practice, often called GitFlow that will help us avoid mistakes and also make it easier to revert changes if needed.

💡 Not familiar with Git branches? Check out this tutorial, or this one, and keep a bookmark for this cheat sheet, or, perhaps the Pro Git book.

🧰 Dev Setup

Read on if you want a fuller setup to work on the documentation. This will allow you to run the documentation locally and also to make changes to the website structure.

🔨 Use this if you just want to build the documentation locally

📊 The R setup

  1. Clone this repository to your computer.
  2. Open a terminal and navigate to the root of this repository.
  3. Although we recommend you have R version 4.2.2 or higher, this should work with R>=3.6.0. You can check your R version by running R --version in your terminal.
  4. Open the R console in this same directory and install renv package:
install.packages("renv")
  1. Run renv::restore() to install all the packages needed for this project. (No need to install packages manually.)
  2. Run renv::activate() to activate the project environment. (No need to run this every time you open the project, just once is enough.)

The Quarto setup

  1. Install Quarto on your computer.
  2. On the terminal, run the following command to start the website locally: 
    quarto preview docs/ --render all --no-browser
    This will read the instructions from _quarto.yml and render the website locally.
  3. Open your browser and navigate to http://localhost:<port>/. That's it!

🔨 Use this if you want to make changes to the core Python package

🐍 The Python setup

  1. Install Python 3.8 or higher on your computer.

  2. Install anaconda or miniconda on your computer.

  3. Create a new conda environment:

    conda create -y -n=venv-vimure python=3.10.8

  4. Activate the environment and make sure you have pip installed inside that environment:

    conda activate venv-vimure

Note: the activate command might vary depending on your OS.

💡 Remember to activate this particular conda environment whenever you reopen VSCode/the terminal.

  1. Install required libraries

    pip install -r src/python/requirements_dev.txt

  2. Install the vimure package in editable mode:

    pip install -e src/python/

Now, whenever you open a Jupyter Notebook, you should see the venv-vimure kernel available.

How to add a feature to the Python package

  1. Create a new branch from develop and name it feature/<feature_name>. For example, if you are adding a new function to the vimure package, you could name your branch feature/add_new_function.

  2. Make your changes to the Python package.

  3. Run the tests to make sure everything is working as expected. See the next section for more details.

  4. Open a pull request to merge your branch into develop. This will allow us to review your changes before merging them into develop.

🧪 Testing

  1. Ensure you have conda's venv-vimure environment activated.

  2. Run the following command:

    python -m pytest -s -vv --pyargs src/python/vimure

  3. If not all tests pass, you can run a specific test by running the following command:

    python -m pytest -s -vv --pyargs src/python/vimure -k <test_name>

    where <test_name> is the name of the test you want to run.

    For example:

    python -m pytest -s -vv --pyargs src/python/vimure -k test_mapping_ego_and_alter`
⚒️ (Advanced) Jon's full setup

⚒️ (Advanced) Jon's full setup

⚠️ Proceed at your own risk ⚠️

I, @jonjoncardoso, like to use R on VSCode (WSL Ubuntu) instead of RStudio. It is a weird setup if you come from R, but it's a good setup for when you need to switch between R and Python all the time (the reality of this project). Feel free to just ignore this stuff but if you want to replicate my setup, just follow the steps below:

  1. Install VSCode
  2. Install WSL on Windows (or on your Mac)
  3. Install the WSL extension on VSCode (if you are on Windows)
  4. Open VSCode and open a new WSL window (Type Ctrl+Shift+P and type WSL: New Window). If on Mac, just open a new window.
  5. Open the terminal on VSCode and install R

When doing R

  1. Install the R extension on VSCode
  2. Install Quarto
  3. Install the Quarto extension on VSCode
  4. When running R notebooks (either .Rmd or .qmd) manually, you will see that some plots do not render with the adequate size. To fix this, follow these instructions.

When doing Python

  1. Install the Python extension on VSCode
  2. Install the Jupyter extension on VSCode

I also use the following VSCode Extensions: