3 of 88

Part 1: GitHub for everyone

Part 2: GitHub for project managers

Part 3: GitHub for content providers (curators, schema developers, ...)

Part 4: GitHub for software developers

GitHub documentation: https://docs.github.com/en

4 of 88

Key concepts

Organization

Repo 1

Repo 2

Issues

Content

Issues

5 of 88

Organizations

An organization is an entity on GitHub that may correspond to an institution (such as a university or a lab) or to a meaningful grouping of repositories.

Example: The Gene Ontology Consortium is an organization

https://github.com/geneontology

6 of 88

Repository (“repo”)

A collection of versioned files (of any type, not necessarily code)
An organization (e.g., geneontology) can have multiple repositories (go-ontology, helpdesk, go-site…)

Organization

Example: geneontology

repository (repo)

Example: go-ontology

Desc: this is where the ontology files are stored

repository (repo)

example: helpdesk

Desc: add description

repository (repo)

example: go-announcements

Desc: add desc.

7 of 88

Repo “landing page”

Menu: code, issues, pull requests, etc.

Summary of most recent change in each subdirectory

Contents of README.md (info about the repo in Markdown format, which is used on GitHub to format text)

Every repo should have a README!

More info about Markdown: https://docs.github.com/en/github/writing-on-github/basic-writing-and-formatting-syntax

8 of 88

Teams

More about teams: https://docs.github.com/en/github/setting-up-and-managing-organizations-and-teams/about-teams

Teams are groups of people in your organization that can have specific access permissions and can be alerted as a group.

9 of 88

Issues

Sometimes called “trouble tickets” or “tickets” -- GitHub calls them issues
Issues can be used to track bugs, new features, questions

Example: https://github.com/geneontology/go-ontology/issues

10 of 88

GitHub issue tracker

Default view lists all open issues (newest first)
Can search, filter, or sort

11 of 88

Search issues

Find issues that have this text anywhere (including in comments)

12 of 88

Filter issues

Start typing name or username

Filter by any of these

Click a label to see all issues with that label

13 of 88

My Issues

My issues landing page: https://github.com/issues
All issues assigned to me: https://github.com/issues/assigned
All issues on which I am @ mentioned: https://github.com/issues/mentioned

More about using issues: https://data2health.github.io/mtip-tutorial/lessons/Lesson6.html

14 of 88

Creating an issue

Go to a specific repo
Go to its Issues
Click “New Issue” (green button)

Here’s a screencast showing the creation of an issue (in the Mondo repo): https://docs.google.com/presentation/d/1sRMROf5jH3lR31fr3I10umJVsH4lb3cEajd-vjHKATs/edit#slide=id.g9b7706cb95_0_95

15 of 88

Issue templates

Some issue trackers have templates to help structure issues

(but you can also just open a blank issue)

16 of 88

Filling in an issue template

Replace this text with your bug description. (Start on a new line, don’t add to the ## line.)

## is Markdown for “header”. Leave this text alone.

Use the “Preview” tab to see how your issue looks

17 of 88

Creating an issue: Best Practices

Search existing issues before creating a new one -- maybe someone else already reported your problem
Give your issue a short but descriptive and actionable title
Describe the problem and the context and include a repeatable example.
Clearly state what needs to be done to close the ticket

Tickets should ideally be actionable units that can be closed via a PR

Flag relevant people with @ (e.g., @nlharris)
Mention related issues with # (e.g., #123)

Use a complete URL to link to tickets in other repos

18 of 88

Example: a good issue

Tag relevant people

Short but descriptive title

Describes the bad behavior, and why it’s a problem

Desired outcome

clear conditions for closing the ticket

19 of 88

Example: a bad issue

Title is vague

No context (Which browser/OS? What URL were you looking at? What happened?)

More about issues: https://guides.github.com/features/issues/

20 of 88

Make issue titles actionable

Non-actionable

Better

More about issues: https://guides.github.com/features/issues/

21 of 88

GitHub preferences

https://github.com/settings

Add profile pic (not necessarily of you--can be any image)
Add info to your personal README
Pin your commonly used repos
Configure notifications

More info: https://docs.github.com/en/github/setting-up-and-managing-your-github-profile/customizing-your-profile

22 of 88

Notifications: How not to get spammed

1) Go to https://github.com/settings/notifications and UNcheck "Automatically watch repositories"

23 of 88

Notifications: How not to get spammed (cont.)

2) Go to https://github.com/watching and click “Unwatch all” to unsubscribe from all repos.

3) Use the “watch” menu for the few repos you really do want to watch.

4) You can also “subscribe” to specific

issues or PRs.

“Participating and @mentions” is a good notification level for most repos

24 of 88

Part 1: GitHub for everyone

Part 2: GitHub for project managers

Part 3: GitHub for content providers (curators, schema developers, ...)

Part 4: GitHub for software developers

GitHub documentation: https://docs.github.com/en

25 of 88

Project management in GitHub

Labels

Per repo
Each issue can have any number of labels

Milestones

Per repo
Each issue can be assigned to only one milestone

Superissues

Issues can include multiple subtasks
See progress to completing

Projects

To Do / In Progress / Done
Can include issues from multiple repos or even multiple organizations

Teams

groups of people in your organization

You don’t need to use all of these together!

26 of 88

Key concepts

Organization

Repo 1

Repo 2

Issues

Content

Milestone

Issues

Contributors

Project

Team

Contributors

27 of 88

Labels

Labels can help group and organize issues
Anyone can filter issues by label
Only project contributors can add/change labels

More about labels: https://docs.github.com/en/github/managing-your-work-on-github/managing-labels

28 of 88

Labels: Best Practices

Make use of use GitHub's default labels: bug, question, enhancement, good first issue, etc.
Define new labels as needed for project management
Lightly coordinate labels across repos in an organization
Labels are not ontologies; don’t overload them. A small simple set consistently applied is better than overly specific inconsistently applied labels

29 of 88

Tip: Avoid too many labels

Probably too many

30 of 88

Tip: Avoid too many labels (cont.)

Better

“Standard” tags

31 of 88

Making connections

Mention people (or teams): @

Cross-reference other issues: #

Start typing part of a name--autofill will make suggestions

Notifies the mentioned user or team

Type an issue number or some text

32 of 88

Superissues

“Superissues” show progress towards completion

Regular issue

33 of 88

Superissues: how to create

In issue description, list tasks preceded by checkboxes

How to add checkboxes:

In Markdown, -[ ] (with a space between the square brackets) makes an unfilled checkbox, -[x] a filled one]

Adding a checklist is a good way to make sure “todos” don’t get lost in a wordy issue!

More about using Markdown to style text in GitHub: https://guides.github.com/features/mastering-markdown/

You won’t see a superissue progress bar unless the checkboxes are in the FIRST block of text in the issue.

34 of 88

Milestones (per repo only)

Often used for a specific date/deadline, like a GO meeting
Like specialized labels on issues
Can filter issues by milestone
See % of issues complete per milestone

More about milestones: https://docs.github.com/en/github/managing-your-work-on-github/about-milestones

35 of 88

Project boards

Example: https://github.com/orgs/geneontology/projects

More about project boards: https://docs.github.com/en/github/managing-your-work-on-github/about-project-boards

36 of 88

Projects can include issues from multiple repos (but not multiple organizations)

Not just issues--can also add “notes”

Mouse over progress bar for more details

37 of 88

Only projects at the Organization level can link to multiple repos

Projects at the Organization level: https://github.com/geneontology/go-ontology/projects

Projects at the repo level: https://github.com/geneontology/go-ontology/projects

38 of 88

Tip: a little issue curation goes a long way

Periodically clean up issue trackers for repos
Edit issue titles to make them meaningful and actionable
Make sure issues are assigned

An issue can be assigned to more than one person (but that’s not always a good idea)

Organize using labels, milestones, projects

39 of 88

Configuring issue templates

Example: https://github.com/geneontology/helpdesk/tree/master/.github/ISSUE_TEMPLATE

Template files go in .github/ISSUE_TEMPLATE

Issue templates can also:

auto-assign different types of issues to different people
automatically add labels

Here’s what users see when they start to create a new issue

More info: https://docs.github.com/en/github/building-a-strong-community/configuring-issue-templates-for-your-repository

40 of 88

Permissions

GitHub has two tiers of permissions, Organization and Repository, and a few permission levels within each:

Organization (e.g. https://github.com/geneontology)

Levels

Member
Owner

Repository (e.g. https://github.com/geneontology/go-annotation)

Levels

Read
Triage
Write
Maintain
Admin

More about permissions: https://docs.github.com/en/github/setting-up-and-managing-organizations-and-teams/repository-permission-levels-for-an-organization

Anyone with Owner or Admin permissions can accidentally delete a repo! 😲

Grant with caution!

41 of 88

Part 1: GitHub for everyone

Part 2: GitHub for project managers

Part 3: GitHub for content providers (curators, schema developers, ...)

Part 4: GitHub for software developers

GitHub documentation: https://docs.github.com/en

42 of 88

Setting up a new repo

Make it public unless there’s a compelling reason not to
Include standard files:

README.md
LICENSE (BSD preferred for software)
CONTRIBUTING.md
Changes.md (changelog)
.gitignore

More info: https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-new-repository

43 of 88

The magic “.github” repo

Add a .github repo to add content that will appear on your organization’s home page (e.g. github.com/YourOrg)
Make sure you make the .github repo Public, not Private!
The shared content should be added to .github/profile/README.md

More info: https://www.freecodecamp.org/news/how-to-use-the-dot-github-repository/

44 of 88

The magic “.github” repo: example

Before / during / after creating .github/profile/README.md

45 of 88

Topics: defining your roles in the GitHub ecosystem

To help other people find and contribute to your project, you can add topics to your repository related to your project's intended purpose, subject area, etc.

Example: https://github.com/topics/obofoundry

More info: https://docs.github.com/en/github/administering-a-repository/classifying-your-repository-with-topics

46 of 88

Adding topics to a repo

Go to the main repo page and find the About section near the top right
Click the gear icon next to About, and add topics to the Topics box

47 of 88

Commit early and often

GitHub helps to integrate the work of multiple people, facilitating communication and peer review and avoiding conflicting changes
To make this work, you need to commit your edits OFTEN
This can be done via direct commits or (even better) with Pull Requests (we’ll show you how)
Commit even if your work is still in progress

(can mark as draft)

48 of 88

Pull Requests (PRs)

PRs let you propose and collaborate on changes in a repo
PRs are a safer, more open, peer-reviewed way to make changes
Collaborators can review and comment on your PR; if needed, you can make additional edits before your changes are merged into the main branch.

See also: the OBO Academy tutorial on pull requests, https://oboacademy.github.io/obook/tutorial/pull-requests/

49 of 88

Creating a PR

Find the file; click the pencil to start editing

Make your edits

More info: https://docs.github.com/en/github-ae@latest/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request

Simplest way: go to the file in GitHub and edit it right in your web browser

50 of 88

Creating a PR (cont.)

If you don’t have write permission, you can only propose changes

If you have write permission, you can commit or start a PR.

PRs are better for all but super-trivial changes.

51 of 88

Creating a PR (cont.)

This pulldown lets you choose regular vs. draft PR

Clicking “propose changes” opens a new page, with another chance to edit your commit message

52 of 88

PRs: draft vs ready to review

Go ahead and make your PR! Mark it as draft if you’re not ready for review
You can mark a PR as draft when you create it, or can convert it later
Draft pull requests cannot be merged (until they become regular PRs)

53 of 88

Linking an issue to a PR

You can link an issue to a PR manually or by using a supported keyword (such as “closes” or “fixes”) in the PR description
When the PR is merged, linked issue(s) are automatically closed

‘#’ followed by part of an issue number or word -> autocomplete

Manual linking

More info: https://docs.github.com/en/github-ae@latest/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue

54 of 88

PRs: peer review

Request reviewer(s) for your PRs

Some repos require a minimum number of reviews to merge a PR

55 of 88

PRs: peer review

Reviewing the PRs of teammates is a duty and a good deed

Comment on others’ PRs line by line or overall
“Vote” on a PR via comments or just choosing “approve”

56 of 88

Requiring reviews to merge

This is a type of “branch protection rule” that a repo manager can add

More info: https://docs.github.com/en/github/administering-a-repository/managing-a-branch-protection-rule

57 of 88

PR review: suggesting changes

In the PR, go to the “Files changed” tab
Hover over the line you want to fix and click the blue “+” to open a comment box
In the toolbar above the comment box, click the small “+/-”button to suggest a change, then edit the text
Suggested change becomes a diff that can be committed

More info: https://haacked.com/archive/2019/06/03/suggested-changes/

58 of 88

Always tie your work to a ticket!

WHO: Anyone working on content managed in GitHub (code, ontology, metadata yaml files, markdown docs, etc.)

Any work you do should be tied to and reference a ticket; don’t work “off ticket”

Make a ticket if one doesn’t exist (unless it’s for something trivial like fixing a typo in text)
If a PR fixes a ticket, then it MUST be linked to that ticket, either via the GitHub UI, or by using the appropriate keyword in the commit

Make a branch AND a PR
Commit early and often
Always save your work in a public PR (just mark as DRAFT if not done yet)

59 of 88

GitHub Pages

Lets you set up a website right from a GitHub repo, with no html or css needed!
By default, the contents of “index.md” will be displayed as the home page
Be patient: changes you make to the files in your repo can take a few minutes to show up on the website
Example:

Repo: https://github.com/geneontology/geneontology.github.io
Corresponding website: https://geneontology.github.io/

More info: https://docs.github.com/en/github/working-with-github-pages/getting-started-with-github-pages

60 of 88

GitHub Pages: from repo to website (example)

File: https://github.com/monarch-initiative/phenomics/blob/master/docs/index.md

Web page: https://monarch-initiative.github.io/phenomics/

61 of 88

GitHub Pages: from repo to website (example, cont.)

But where did the top part about “Phenomics Workshop Series” come from? In this case, a Jekyll template.

https://github.com/monarch-initiative/phenomics/blob/master/docs/_config.yml

62 of 88

Part 1: GitHub for everyone

Part 2: GitHub for project managers

Part 3: GitHub for content providers (curators, schema developers, ...)

Part 4: GitHub for software developers

GitHub documentation: https://docs.github.com/en

63 of 88

What’s the difference between git and GitHub?

Git is a version-control system (like svn and cvs-- remember those?)
How you can use git:

Via GitHub
Check out repo onto your local file system, edit locally, create branches, store changes on the server via command line
Use a git client (e.g. GitHub Desktop)

64 of 88

Why use GitHub?

GitHub is a website that wraps git along with other useful functionality, including

pull requests
code review
issue tracking
communication
project management
access control

65 of 88

More about git

James Overton & Nico Matentzoglu put together a nice tutorial about using git (focusing on using git from the (Unix) command line rather than from GitHub): http://swcarpentry.github.io/git-novice/
Starting in August 2021, GitHub stopped allowing users to perform GitHub operations from the command line or from other clients using their personal passwords (https://github.blog/2020-12-15-token-authentication-requirements-for-git-operations/). Instead, you will need to generate a Personal Access Token.

See Seth Carbon’s document about how to do this

66 of 88

Best practices for collaborating

Make repos public if at all possible
Work to a ticket

Your work should address a specific bug report or feature request that has been clearly described in a ticket
Link your work to the ticket by referencing it in your PRs with # (e.g., “fixes #123”)

Propose changes in a PR (draft, if it’s not ready to be merged)
Ask for reviews
Comment on other people’s PRs

67 of 88

Work to a ticket

In a well-run project, there should be a ticket (issue) for everything that needs to be done.
Your PR should reference (with “#”) the issue(s) that it addresses (e.g. “fixes #123”)

Keywords: close, closed, closes, fix, resolve

When the PR is merged, the linked issue(s) will automatically be closed.

More info: https://docs.github.com/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue

68 of 88

Closing issues manually

More about issues: https://guides.github.com/features/issues/

New (as of 2022): you can close issues as “not planned” (default is “completed”)

69 of 88

Branching and forking

Forking creates a copy of a repo

Clicking the fork button in GitHub does a “git clone” and creates a new origin/master.
Forks are typically used to either propose changes to someone else's project or to use someone else's project as a starting point for your own idea.
More info: https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/working-with-forks

Branches are like ‘construction zones’

Branches are best used as temporary places to work on changes, with the intent to later merge the branch with the origin.
Each repo has one default branch, and can have multiple other branches.
A PR creates a temporary branch for your changes; merging the PR merges the changes into the “base” branch
More info: https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-branches

70 of 88

Branching from the command line

git fetch (make sure your local copy is up-to-date)
git checkout master (start on the master branch)
git checkout -b your-branch-name (create a new branch named for the change you're making)
make your changes in your local copies of the file(s)
git status and git diff (inspect your changes)
git add --update src/ (add all updated files in the src/ directory to staging -- replace src/ with appropriate directory name)
git commit --message "Description, issue #123" (commit staged changes with a message; it's good to include an issue number)
git push --set-upstream origin your-branch-name (push your commit to GitHub)
open https://github.com/[repo] in your web browser and click the "Make Pull Request" button.

(These instructions adapted from https://github.com/obi-ontology/obi#making-changes)

71 of 88

Comparing branches in a PR

Option to hide whitespace changes

Unified view

Split view

72 of 88

Finding the file that was changed

The “Files changed” view just shows the differences
To see the whole original file, use the “...” menu below “Review changes” and select “View file”

73 of 88

Commenting on a PR: general comments

In the “files changed” view, click the green “Review changes” button and enter your comments.

74 of 88

Commenting on a PR line by line

In the “files changed” view, hover over the line where you'd like to add a comment, and click the blue +.

To add a comment on multiple lines, click and drag to select the range of lines, then click the blue +.

When you're done commenting on specific lines, click Start a review.

There you can add general comments.

More info: https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/reviewing-changes-in-pull-requests

75 of 88

Resolving merge conflicts

If the changes in your PR conflict with the base branch, you must address the conflict before the PR can be merged
You can use the “conflict editor” to resolve simple merge conflicts
If the merge conflicts are more complicated, you’ll have to decide which changes to incorporate from the different branches, edit the affected file(s) to resolve the conflicts and remove the conflict markup, and then use the command line to commit.

base version (above the ======)

your version (below the ======)

More info: https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/addressing-merge-conflicts

If you have questions, please

<<<<<<< HEAD

open an issue

=======

ask in our Slack channel

>>>>>>> branch-a

If you have questions, please open an issue, or, if it’s urgent, ask in our Slack channel.

76 of 88

Merging PRs

To merge a PR, you must have write permission for the repo
Merge options:

Retain all the separate commits in a feature branch
Squash all commits into a single commit

Repo must allow squash merging

Rebase individual commits from the head branch onto the base branch.

More info: https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-request-merges

77 of 88

Don’t commit secrets

Even if your repo is private, be sure your commits don’t include secret things like passwords or email addresses
https://github.com/awslabs/git-secrets helps prevent you from accidentally committing passwords etc. to git

78 of 88

GitHub Actions

GitHub Actions are event-driven workflows
For example, every time someone creates a PR, you can automatically run a software testing script (like Travis CI)
Things actions are good for (examples):

CI -- checking that PRs don’t break anything
automatically deploying to PyPI
deploying a website, e.g. via mkdocs
releasing derived artifacts

More info: https://docs.github.com/en/actions/learn-github-actions/introduction-to-github-actions

79 of 88

GitHub Actions

An event (e.g. a commit) can be set to trigger a workflow, which contains a job. The job then uses steps to run actions in order.

More info: https://docs.github.com/en/actions/learn-github-actions/introduction-to-github-actions

Workflows live in YAML files in the .github/workflows directory.

80 of 88

GitHub Actions

Simple example: Run a QC workflow when something changes in master

https://github.com/geneontology/go-ontology/blob/master/.github/workflows/qc.yml

name: CI

# Controls when the action will run.

on:

# Triggers the workflow on push or pull request events but only for the master branch

push:

branches: [ master ]

pull_request:

branches: [ master ]

# Allows you to run this workflow manually from the Actions tab

workflow_dispatch:

# A workflow run is made up of one or more jobs that can run sequentially or in parallel

jobs:

# This workflow contains a single job called "ontology_qc"

ontology_qc:

# The type of runner that the job will run on

runs-on: ubuntu-latest

container: obolibrary/odkfull:v1.2.23

# Steps represent a sequence of tasks that will be executed as part of the job

steps:

# Checks out your repository under $GITHUB_WORKSPACE, so your job can access it

- uses: actions/checkout@v2

- name: Run ontology QC checks

env:

DEFAULT_BRANCH: master

run: make -j 4 ROBOT_ENV='ROBOT_JAVA_ARGS=-Xmx6G' travis_test

More examples:

Build an ontology and make a zip file: https://github.com/obophenotype/mammalian-phenotype-ontology/blob/main/.github/workflows/build-ontology.yml
Make and deploy documentation: https://github.com/microbiomedata/nmdc-schema/blob/main/.github/workflows/build-deploy-documentation.yaml

81 of 88

Actions: see what happened

Click for more details about run

82 of 88

Migrating from Travis CI to GH Actions

(Instructions from Nico Matentzoglu)

Add a folder .github/workflows in the top level of your github repo
Copy the relevant script into that folder
Go to your .travis.yml file (top level of repo) and check the script section (e.g., cd src/ontology && sh run.sh make test) and adjust the “steps” section in the qc.yml file accordingly (e.g., run: cd src/ontology && make ROBOT_ENV='ROBOT_JAVA_ARGS=-Xmx6G' test)
Commit the test
Next time you create a pull request or commit something, the test will be run and send you email
Now you can deactivate your Travis checks: Go to your travis site, click on “More options-->Settings” and deactivate “Build pushed branches” and “Build pushed pull requests”:

More info: https://docs.github.com/en/actions/learn-github-actions/migrating-from-travis-ci-to-github-actions

83 of 88

Badges

Add badges to show CI status
Typically added to README.md, but can add to any file
Example: https://github.com/biolink/biolink-model/blob/master/README.md

84 of 88

GitHub permission levels

Permissions can be set at the organization level and at the repository level.

Organization (e.g. https://github.com/OBOFoundry) permission levels:

Owner

Complete administrative access (could even permanently delete a repo)
Should be two trusted people in the organization

Member

Normal permissions

Repository (e.g. https://github.com/OBOFoundry/OBOFoundry.github.io) permission levels:

Admin: full access to the project, including sensitive and destructive actions like managing security or deleting a repository
Maintain: Recommended for project managers who need to manage the repository without access to sensitive or destructive actions
Write: for contributors who need to directly commit to your project
Triage: for contributors who need to manage issues and PRs without write access
Read: for non-code contributors who want to view or discuss your project.

Can still create issues and make PRs!

More info: https://docs.github.com/en/github/setting-up-and-managing-organizations-and-teams/managing-access-to-your-organizations-repositories

85 of 88

Example structure for teams and permissions

Example from OBO (James Overton)

OBO Admin

description: A small group of active Operations Committee members who have multiple years of in-depth experience with OBO and GitHub
organization permissions: Owner
repository permissions: Admin

OBO Foundry Operations Committee

description: All current members of the OBO Foundry Operations Committee
organization permissions: Member
repository permissions: Write

OBO Community:

description: Anyone with current responsibility for maintaining the registry or PURL entries for an OBO project, or who needs to be assigned an issue.
organization permissions: Member
repository permissions: Read -- includes creating issues and Pull Requests

Public access (no team membership)

description: anyone logged in to GitHub
organization permissions: None
repository permissions: Read -- includes creating issues and Pull Requests