Github Issues, Branches, and Projects

Working collaboratively on Github and organizing tasks

Matthew DeHaven

March 31, 2024

Course Home Page

Lecture Summary

• Task Management
  • Github Issues
  • Github Projects
• Collaborating
  • Branches
  • Pull Requests

Project Organization

A crucial aspect of any project is organizing tasks.

• especially with teams of people

• but also true for solo work

I am going to show you today the tools built in to Github for organizing tasks and workflows, and how they aid in working with others.

Github Issues

Github Issues

GitHub Issues are items you can create in a repository to plan, discuss and track work. - Github Docs

Issues are

• linked to a repository
• have a title and description
• and allow for further comments

They can be either

• “open” — work in progress, or need to do
• “closed” — finished

Opening an Issue

Issues for public projects can be opened by anyone (by default).

• This allows users to report literal “issues” with a product

• Then a developer is assigned that issue
• and closes it when it has been fixed.

For private projects, only you and your collaborators can open an issue.

Issue Quickstart

Each repository has an “Issues” tab.

We are going to follow along the Github Quickstart for Github Issues.

Opening a New Issue

• Click on the “Issues” tab

• Then click the green “New issue” button

This will open an editor in your browser for the issue.

Writing an Issue

Issues have a title and description.

Github Issues are Markdown

The description is rendered as markdowon, allowing you to add

• formatting (headers, bold, italics, etc.)
• URL links
• code blocks
• tag other Github users

Adding a Task List to an Issue

This will be rendered as an interactive list that you can check-off as you complete the items.

Adding Labels to an Issue

Labels can be added to the right. Some are generated by default but you can add your own.

Adding Milestones to an Issue

Milestones let you add a date-based target for completing this issue (or a set of issues).

Assigning the Issue

Issues can be assigned to yourself or to other Github users working on the repository.

Adding an Issue to a Github Project

Issues can grouped together into projects, which we will look at soon.

Communicating on an Issue

A big benefit of issues the ability to continue commenting on open issues.

This allows discussion and clarification of the task, and progress reports.

Comments have all the same markdown styling options.

Why use Issues?

You might think that these issues look a lot like an email-thread you’ve had with an advisor or professor.

But there are big differences:

• issues are connected to a repository
• issues allow assignees, milestones, labels
• issues are a documented record

Email is not a task management system.

There are many other task management software (Asana, Wrike, Flow) if you don’t like Github.

Task Management

Task management is most important when you are working with others.

This is true when collaborating

• who does which step?

Or when you are the research assistant for a professor

• what are my tasks?
• when are they due?
• what exactly do I need to do?

And it remains crucial when you are working by yourself…

Task Managing Yourself

Treat yourself as your own RA - Camilla Adams (my friend)

• break down your research project into tasks

• assign them to yourself

• do the tasks

This often means keeping a todo list on a piece of paper, or in a Word document. But using a task manager system is much more effective.

• Solo projects are collaborations between your current self and your future self

Github Projects

Github Projects

A project is an adaptable spreadsheet, task-board, and road map that integrates with your issues and pull requests on GitHub to help you plan and track your work effectively.

You can create and customize multiple views by filtering, sorting, grouping your issues and pull requests, visualize work with configurable charts, and add custom fields to track metadata specific to your team. - Github Docs

Projects Overview

Projects are attached to your personal profile (not a repository).

• Projects compile issues and allow
  • different views (tables, “storyboards”, or “roadmaps”)
  • custom fields (priority, status, due dates, etc.)
  • combine issues from multiple respositories

Example Project Board

Example Project Table

Example Project Roadmap

Adding Issues to Projects

The easiest way to add an issue to a project is when creating it.

Adding Already Opened Issues to Projects

You can use the same method to add issues that have already been opened to a project.

Once added, you can then fill out any additional custom fields.

Addding an Issue from a Project

From a project, you can create a “draft” issue.

You can write the description, set all of the custom fields, etc.

Then “convert” the draft issue to a real issue for a specific repository

• i.e. assign it to a repository

Github Projects Automations

Github Projects allow for custom automation as well.

• automatically add all issues from one repository to a project
• mark as “done” any issue that is “closed”
• etc.

I want to note that these are possible, but I don’t think you need to use them to have Github Projects be effective.

Github Project Benefits

The major benefits of Github Projects:

• Custom fields
  • Priority, due dates, anything you can imagine

• Different views
  • “Board”, “Table”, “Roadmap”
  • all better than the default list of issues

• combining issues from multiple repositories in one place

Github Projects Summary

Github Issues provide the basic tools needed to manage tasks.

Github Projects provides the advanced tools and the nice “visual” views.

Sometimes, Github Issues will be enough, but for any big research project, I recommend trying to use Github Projects too.

Git Branches

Adding Collaborators

For any respository on Github, you can add collaborators.

• Go to the repository’s “Settings”

• then “Collaborators”

• and add their Github username

Working with Collaborators with Git

As long as you and your collaborators are not editing the same files,

you can push and pull to same Github repository.

But if you and your collaborator have conflicting commits

• i.e. you both edited the same file with different changes

then you will not be able to push to the repository without first resolving the conflict.

Resolving Conflicting Local vs. Remote Commits

One way to solve an out of sync local repository is to…

• “undo” your local commits
• pull the remote changes
• then redo your commits (or decide some of them are no longer needed)
• then push to the remote repository

Zero Branches

The default “branch” is called “master” or “main”.

This is how you have been using Git repositories so far.

Zero Branches

The default “branch” is called “master” or “main”.

This is how you have been using Git repositories so far.

Branches

“Branches” allow you to split your Github repository into two (or more) states, each with their own set of commits.

Branches Overview

Branches allow you to develop features, fix bugs, or safely experiment with new ideas in a contained area of your repository. - Github Docs

Branches are like copying your entire repository to a new folder.

• Great for experimenting with new features
• Great for collaborating

Merging Branches Back to “Main”

When you are happy with the state of branch, you will want to merge it back to the “main” repository.

Github calls this merge a “pull request”.

Github Pull Requests

Github Pull Requests

Pull requests let you tell others about changes you’ve pushed to a branch in a repository on GitHub. Once a pull request is opened, you can discuss and review the potential changes with collaborators and add follow-up commits before your changes are merged into the base branch. - Github Docs

Opening a Pull Request

Once you have a branch that you want to merge back onto “main”,

• Open a “pull request” for your branch on Github

Pull requests will

• Compare your commits to the current state of “main”.
  • Are there any conflicts?
  • If yes, you can resolve them—by choosing one version to keep.
• Runs any tests you have written in Github Actions
• Allows you to request “review” from another collaborator

Branches

After a succesful pull request, you can delete the branch.

• This keeps its history, but you can’t commit to it anymore.

Branch Models

Branches are a tool and there are a lot of ways to use them in practice:

• Zero Branches
  • just use “main”

• Development Branch
  • “main” for finished work
  • a “development” branch for work in progress

• Feature Branches
  • “main” for finished work
  • a new feature branch for each feature (often one for each open issue)

• and more…

Branches Overview

Branches complicate the flow of Git commits

but they have real benefits for working with others.

Personally, I have yet to find them that useful when working on my own.

• But some people recommend using branches all the time.

Lecture Summary

Lecture Summary

• Task Management
  • Github Issues
  • Github Projects
• Collaborating
  • Branches
  • Pull Requests

In Class Example

Example

• Creating Issues
• Creating a Project
  • Adding issues to the project
• Creating a branch
  • Creating a Pull Request

In Class Exercise

With a classmate next to you…

1. Partner 1 creates a Github repository, adds Partner 2 as a collaborator

2. Both Partners clone the repository to their machines

3. Both Partners edit the Readme files (with different edits)

4. Both commit and try to push to Github

Using the same repository,

1. Both partners create a branch on Github

2. Both partners edit the readme file for your branch

3. Partner 1 submits a pull request, merge it onto “main”

4. Partner 2 submits a pull request, resolve the conflicts and then merge onto “main”