LNCD CODE REVIEW AND DATA CLUB

A repository for the Laboratory of Neurocognitive Development's code review and data club!

This is a central location for

• data_club presentation series (example commands) or
• code_review files and annotation (example commands)

Sign up on the roster sheet (https://tinyurl.com/lncd-data-code-club)

Adding Data Club Materials

You'll need this repo cloned locally. Jump to Repo Setup for that.

Please create a new directory titled topic_date_initials in the most relevant folder in data_club/, and put your materials there. For example: data_club/neuroimaging_methods/myelinimaging_2024-09_vjs

In a terminal, you can do this like

mkdir -p data_club/neuroimaging_methods/myelinimaging_2024-09_vjs
cp ~/docs/mypresentation data_club/neuroimaging_methods/myelinimaging_2024-09_vjs
git commit -Am 'adding myelin imaging presentation' && git push

For more explict commands jump to Data Club.

Adding Code to Review

You'll need this repo cloned locally. Jump to Repo Setup for that.

1. create a new branch like yyyymmdd_yourinitials
2. add code to a folder like code_review/yourintials/
3. push to your local fork
4. submit a pull request on LabNeuroCogDevel/lncd_dataclub remote
5. look at the reviews

For more explict commands jump to Code Review.

---

Git help

Getting a terminal

Terminal is your chat window with the computer.

• macOS: use the built in Terminal app. Alternatively, brew install --cask wezterm or brew install --cask iterm2
• Windows: use Git Bash (also from explorer context menu Git Bash Here) bundled with the official git download. NB. check "Enable experimental support for pseudo consoles" or you'll need to use winpty gh ... for interactive prompts.
• Linux: likely to have gnome-terminal,konsole, or xterm already

Getting started with the repo

For local access to this repo and all of its contents, you need to git clone the github remote onto your computer. For write access, you'll also need to help github confirm your identity. We'll use ssh key authentication -- it's slightly more ergonomic than generating and using a http auth token.

Install gh helper program

Download gh, the github cli tool. This tool enables command line access to github (vs git) specific tasks: key management, forking, pull requests, and issues. On MacOS, you can use brew to install gh. This will lower the number of times you need to switch between the web browser and terminal.

1. install gh
2. authenticate with github

First install

# on macOS, see https://brew.sh
brew install gh

# on linux (quick and dirty, no man page; 2024-08-17)
curl -L https://github.com/cli/cli/releases/download/v2.54.0/gh_2.54.0_linux_amd64.tar.gz |
  tar -C ~/bin/ --strip-components=2 -wildcards -tvzf - '*/bin/gh'

On windows:

1. download the exe from https://cli.github.com and install
2. close and relaunch any open "Git Bash Here" from file browser context menu

Then authenticate

gh auth login

On windows (e.g. file browser context menu Git Bash Here), you need to prefix the command with winpty

winpty gh auth login

Github SSH key auth setup

1. copy ssh keys from ~/.ssh/id*pub (create if missing with ssh-keygen)
2. paste key on github: https://github.com/settings/keys (or use gh)

# contents of a public id file
# copied to new key on https://github.com/settings/keys
head ~/.ssh/id*.pub

# if above is empty, first run
ssh-keygen

Alternatively, skip pasting into the browser by using gh

gh ssh-key add ~/.ssh/id_ed25519.pub

Repo Setup

After gh is installed (help) and ssh keys are setup (help), in a terminal, run

# get remote data locally
git clone [email protected]:LabNeuroCogDevel/lncd_dataclub.git
cd lncd_dataclub

git config push.autoSetupRemote true               # dont complain about making branches
gh repo fork --remote                              # create a personal fork
gh repo set-default LabNeuroCogDevel/lncd_dataclub # but default pr/issues on shared

Congrats on finishing the setup. You may want to jump to instructions for Data Club or Code Review.

Specific repo setup notes

The above clone and fork sequence configures two remote sources

• origin is your personal github fork
• upstream is the canonical group managed LNCD repo

You can push to and pull from either. They do not have to be in sync -- neither with each other nor with your or anyone else's local copy. Each can contain their own branches. These names are an artifact of the git and gh command defaults. You can have an arbitrary number of remotes with any name you like.

See cat .git/config for more info and confirmation.

[remote "upstream"]
        url = [email protected]:LabNeuroCogDevel/lncd_dataclub.git
[branch "main"]
        remote = upstream
[remote "origin"]
        url = [email protected]:WillForan/lncd_dataclub.git

---

Data Club

You'll need lncd_dataclub files cloned locally on your computer. See Repo Setup.

Adding files to the repo

Want to upload code or files to the repo so others can access them? Put the files in your lncd_dataclub directory (local clone) and then send (add, commit, push) them to the "remote" repo (github.com) for everyone to access.

cp my_elegant_code.sh lncd_dataclub/data_club/ # 1. put code-to-share into your local clone
git add data_club/my_elegant_code.sh           # 2. tell git to track the file
git commit -m "good code review vibes"         # 3. commit your addition w/ an annotation
git push upstream                              # 4. send to remote (github)

Pulling files from the repo to your local clone

So, you cloned the repo a while ago, but now someone has uploaded some new, elegant code! To access these new files, you can "pull" them down from the remote repo to your local glone

cd lncd_dataclub     # go to the local repo
git pull upstream    # ta-da! new files and changes appear!

---

Code Review

You'll need lncd_dataclub files cloned locally on your computer. See Repo Setup.

Create a pull request

Following the branch and pull request steps outlined in Adding Code to Review

cd lncd_dataclub                     # 0.1 enter repo on local computer
git pull upstream                    # 0.2 make sure we're up to date 
git checkout -b 20240817_wf          # 1. create a new branch
                                     # 2. add files to review
mkdir code_review/wf/
cp code-to-review.R  code_review/wf/

git add code_review/wf/*             # 3. tell git about those files
git commit -m 'sus code does x'      # 4. annotate addition
git push origin                      # 5. send changes to your github.com fork
gh pr create --fill                  # 6. create pull request to upstream LNCD github repo
                                     #    on Windows, prefix cmd with: winpty

You can follow the github URL printed out by gh pr create to see reviews and annotations others submit.

NB. Use git branch to see the current branch. Use git switch main to get back to the main branch