contributing_guidelines/code_review.qmd at main · Meshinchi-Lab/contributing_guidelines · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
---
title: "Code Review"
format:
  html:
    code-fold: false
    code-tools: true
    toc: true
    number-sections: true
author: "Jenny L. Smith"
---

## Guidelines

These meetings are truly **team gatherings** and are designed to be a **learning environment**. Since, everyone will have different levels of experience using these tools, a primary tenet of these meetings will be **repetition of our processes** so that we can work together effectively and adapt as needed.

We will model our code review style using [this document](https://github.com/mawrkus/pull-request-review-guide?tab=readme-ov-file#a-practical-guide-for-better-faster-code-reviews). The most important sections are highlighted below.

**We will prioritize:**

  - [**Positive and actionable feedback**](https://github.com/mawrkus/pull-request-review-guide?tab=readme-ov-file#offer-encouragement--appreciation--give-positive-feedback)

  - [**Empathize and have an open mind**](https://github.com/mawrkus/pull-request-review-guide?tab=readme-ov-file#empathize--the-other-person-is-you)

  - [**Leave comments in your code**](https://github.com/mawrkus/pull-request-review-guide?tab=readme-ov-file#clarify-the-code-first--help-future-developers)

  - [**Add references and examples**](https://github.com/mawrkus/pull-request-review-guide?tab=readme-ov-file#provide-references)

We will also reference this checklist and modify this as needed for [bioinformatics coding](https://roadmap.sh/best-practices/code-review).

## Overview

### Agendas

Meeting agendas will be hosted on the github repository ["contributing guidelines" discussions section](https://github.com/Meshinchi-Lab/contributing_guidelines/discussions).

If you have any questions or suggestions, please post them discussions section as well! This will be an evolving process as we develop our own bioinformatics team best practices.

### Meeting Descriptions

There are two Microsoft Teams recurring meeting series for git and github. In general, meetings will always have a virtual component in order to share our screens and easily view each others code.

1. **"Code Review - paired programming":**

  - *Frequency:* 1x a week on Wednesdays

  - *Description:*

    - focused on gaining experience and familiarity with using `git`, `gh` github CLI commands, and github web features.

    - review our commits and commit history together

    - push changes to the lab github organization


2. **"Code Review - formal review":**

  - *Frequency:* 1x every 3 weeks

  - *Description:*

    - a more in-depth discussion of the technical components of our code

    - ask specific questions and troubleshoot errors

    - get feedback on how to improve the efficiency of our code


## Code Review - paired programming

Weekly code review / code commit gatherings to ensure:
- only committing changes that we expect
- have not added any files that may not belong on github, such as PDFs or power point presentations
- have not added any sensitive data.

### Meeting Format:

1. Open questions (10 min)

2. We will work in pairs to commit changes, review our commit history and which files should be hosted on github (35 min)

3. Push changes to the lab github repositories (15 min)

### Git and Github

1. Review our diffs and commit history

  - [VSCode](https://code.visualstudio.com/docs/sourcecontrol/overview#_working-in-a-git-repository)
  - [RStudio](https://docs.posit.co/ide/user/ide/guide/tools/version-control.html#integrations)

``` bash
REPO="Meshinchi-Lab/2025.06.23_Example_Repo"
cd $REPO
git status
git diff
```

2. Once we all completed the code review / code commit partner checks, then you can push changes to the repository.

``` bash
git push
```

3. check that the repository looks the way you expect it to look using the following command:

``` bash
gh repo view --web "$REPO"
```

## Code Review - formal review

A 1x every 3 weeks recurring code review meeting for the bioinformatics team to discuss questions, troubleshoot code, and make code improvements.

### Meeting Format

1. Open questions (10 min)

2. Presentation of code by person 1 (15 min)

3. Presentation of code by person 2 (15 min)

4. Presentation of code by person 3 (15 min)

5. Recap on what changes to be made (5 min)

We will then wait until the following "Paired Programming" meeting to push any changes.