Our Group’s Common GitHub Use Cases

High-level overview

We use GitHub for many tasks:

  • Conduct careful versional control on all projects (solo or collaborative)
  • Keep track of our lab meeting agendas and presentation order
  • Maintain the group webpage
  • Maintain this lab manual

This is easier said than done! See below for some helpful resources and code.

GitHub for Puppies

These code blocks and recommendations can be helpful for routine tasks, but may require knowledge and set-up that they don’t explicitly acknowledge. To use these recipes well, you should work through the recommended tutorials and resources above (or have commensurate knowledge).

Keep track of lab meetings

This is our lab meeting repo.

The person responsible for organizing and leading lab meetings will:

We can organize this better!

We should probably have subdirectories on the main branch for each term and avoid the complicated branch structure we currently use.

  • Once per term, create a new branch named for the term (e.g., winter25) and update the README with the meeting details and schedule.
  • Once per term, update the main branch README.md to reflect the branch we are currently on.
  • Every week, add a new subdirectory for the meeting of that week (e.g., 1-15/) and add an agenda.md file. Include a link to the presenter’s slides if possible. Update the meeting schedule with a link to the week’s agenda.md.

We only expect other lab members to view this repo.

Contribute to the webpage

This is our webpage repo.

We may want to migrate to Quarto!

The main interactions with the webpage is to add/remove a member profile. Quarto could simplify this quite a bit, and synchronizing tech stacks for the manual and webpage could make it simpler for a wider range of contributions to each.

The person reponsible for maintaining the webpage should follow, and add to, the README.md as appropriate for various tasks.

Occassionally, other lab members may want to propose changes. You can always post an Issue to the repo. If you want to directly implement changes, the workflow for this is to:

  • Clone the repo to your local machine
  • Create a new branch named parsimoniously for the change you’d like to make. For example, when we added this web manual to the navigation bar at the top of the webpage, we did the following workflow after cloning:
    • git checkout -b web-manual
    • made changes and tested locally
    • git add .
    • git commit -m add link to lab manual on web page resources
    • git push -u origin web-manual
    • On the web repo, open a PR with a detailed description and assign the task to Klaus and the person in charge of the webpage

Contribute to this manual

This is the web manual repo.

We need to define the workflow for contributing to it before we add more instructions here.

Set up and maintain your research project

If this is your first project in the group, check out the metarepo documentation and start from the IM3 template. You should:

  • Make keller-lab the owner
  • Generally, set the repo to private while you are first beginning your work
  • Clone the repo (ideally to both kasper and your local machine)
  • Begin modifying the template to better meet your needs. For example:
    • We often add data/ to our .gitignore because we like having this in our project directory
    • Some of us prefer renaming scripts/ to workflow/ because we are special
    • You may want to add other directories, .yml files, etc.,

If you have your own project template (e.g., maybe you like Cookiecutter Data Science), please use your template!

No matter how you initialize your project, please keep the following principles in mind:

  • git add and git commit often, and make sure your commit messages are informative (and make you feel more comfortable reverting, if necessary).
  • Keep reproducibility in mind (e.g., use relative filepaths, update your README as you go, keep your kapser & local machine repos up to date with each other and make sure you can run code on both machines, etc.,)
  • In general, separate functions from analysis.
    • Study the UNSAFE directory structure (esp. the pyproject.toml) and see how we use it in the examples/ directory. See here
    • Use software packages you develop for various functions as submodules in your analysis-focused projects. For example, see here - lab members can reach out to Adam for access if this repo is still private when they take a peek.

Check out our example repositories to see neat code directory structures. Reproduce these examples to see how the data gets structured for ideas on how to structure your unique project well.