Collaborating on GitHub#

Project planning and collaborating on GitHub revolves around GitHub Issues and Pull Requests. This will walk you through a workflow for managing a project with multiple contributors with GitHub Projects, Issues, and Pull Requests.

Review: Branches and Pull Requests#

What’s a pull request?#

Pull requests let you tell others about the changes you’ve pushed to a branch on GitHub.

They allow collaborators to discuss and review potential changes before they’re merged.

How do you make a pull request?#

  1. Create a branch in your local repo.

    $ git checkout -b octo-repo

  2. Make changes and commit them.

  3. Push your branch to GitHub.

    $ git push origin octo-repo

  4. Navigate to the main page of your GitHub repository and click Compare & pull request

    Screenshot of the banner with the Compare & pull request button

Examples#

Discussion on a pull request from the facebook/react repo

Discussion on PR#6046 from the facebook/react repo#

Code review on a pull request from the facebook/react repo

Code review on PR#13509 from the facebook/react repo#

Project Planning with Issues#

GitHub Issues#

GitHub Issues help you track ideas, feedback, tasks, or bugs.

Open issues from the facebook/react repo

Open issues from the facebook/react repo#

  • Issues are often used alongside external project management tools

    • Ex.: Jira, Trello, Notion

  • In 2022, GitHub launched their own project management tool called GitHub Projects

GitHub Projects#

GitHub Projects is a tool for planning and tracking work on GitHub.

  • Can view issues and PRs as a spreadsheet, task-board, and road map

  • Allows you to add metadata with custom fields (ex.: dates, iterations, text…)

  • Automatically add/update issues and PRs using workflows

  • Build reports and graphs

There are a lot of different ways you can take advantage of these features.

We’ll show you a simple workflow for using GitHub Projects as a task-board.

How to create a project#

  1. On the main page for your repo, navigate to the Projects tab

  2. Click the green dropdown button to select New project

  3. On the next page, create a new project from the Team backlog template

Dialog box for creating a new project

Here’s a demo project we’ve already created using the “Team backlog” template

Using the board view#

The board view can be used as a kanban board

Screenshot of a task board

  • Columns represent different stages of work

  • Cards are moved from left to right as they progress through each stage

The “Team backlog” template comes with these columns:

🆕 New

New/draft issues coming in that need to be triaged.

📋 Backlog

Issues that have been triaged but not ready for active development.

🔖 Ready

Issues you’re planning to work on during this sprint.

🏗 In progress

Issues being worked on right now.

👀 In review

Issues with pull requests that are ready for code reviews.

✅ Done

Issues with pull requests that have been merged.

Getting Started#

Start adding tasks#

When you add a task, it’ll appear as a draft issue

Adding a new task

Start big, then break tasks down with checklists

Breaking a task down into subtasks

Convert to issue#

When you’re ready, convert tasks to issues

From the issue’s discussion page, you can convert subtasks to issues too

Issues with subtasks are also known as tracking issues

Example tracking issue

During sprint planning#

Decide what to work on and move cards to the “Ready” column

  • Assign tasks to teammates using the “assignee” field

  • Rate how urgent/how much effort for each task

Start working on your issue#

GitHub can create a branch for your issue.

On the issue’s discussion page, click on the gear icon next to Development › create a branch

Create a branch to checkout locally

Copy and paste the commands in the terminal to checkout the branch

When making a PR for the branch, the issue and PR will automatically be linked

Other ways to link issues and PRs

You can also create linked issues and pull requests using a keyword or manually. To learn more, see About linked issues and pull requests

Create a PR#

Create a draft PR to keep teammates updated on your progress

Example draft PR

When your changes are ready to be reviewed, click Ready for review

Merging changes#

  • Reviewers can suggest changes or approve them

  • Merge the PR once it’s been approved

  • Merging a PR will automatically close any linked issues

Looking Ahead#

Coming up#

Practice with GitHub Learning Labs!