Team Contributing Guidelines

While our team is composed of members from different backgrounds, we strive to adhere to a shared set of contributing and style guidelines. This ensures a consistent “feel” of our team’s products, regardless of which team member took the lead on a particular task.

Caution Required for SciComp Only!

This document is meant to focus primarily on our internal processes for contributing. If you’re not a member of this team, we hope you find this document valuable but you should also feel free to use our guidelines as a starting place rather than absolute rules.

Version Control & GitHub

We use Git & GitHub extensively both because it’s extremely useful for our profession and it helps us ‘walk the walk’ with regard to our guidance to working groups. However, depending on whether the edits you are making are minor or more substantial, you’ll want to use different approaches. See below for details on either context.

For minor changes, do the following:

  1. Communicate with the team (both ours and the relevant working group’s) to avoid merge conflicts
  2. Make commits directly to main

For major changes, do the following:

  1. Communicate with the team to avoid merge conflicts
  2. Open a branch with an intuitive but concise name
  3. Make any needed edits
  4. Open a pull request when you are confident your edits are largely complete
  5. Request a review from a teammate
  6. Make any edits they suggest, (6) merge the PR, and (7) delete the branch.

Regardless of the scope of your edits, commit frequently with informative messages. As much as possible, use the style of “Conventional Commits” in your commit messages. See here for a nice summary of the highlights of that approach.

Style Guide

For folder/file names and in code, please follow the following style tips:

  • Use all lowercase
  • Related files/objects should have a shared file prefix (e.g., wrangle_...)
    • For files that have an inherent order, use zero-padded numbers as the prefix (e.g., 01_, 02_, etc.)
  • Use underscores (_) for separating major pieces of information and hyphens (-) in lieu of spaces (e.g., 01_find-area.R, harmonize_spp-rich-info.py, etc.)

File Paths

When we write code–for ourselves or for working groups–we use operating system (OS) agnostic file paths.

In R, this means using the file.path() function (from base R) to stitch together elements (e.g., file.path("data", "raw_2024.csv")). In Python it means using the join function from the path module of the os library (e.g., os.path.join("data", "raw_2024.csv")).

If you plan on re-using a file path, assign it to an object/variable (R/Python) to avoid typos/errors when re-using the file path.