Planning and tracking work for your team or project

Introduction

You can use GitHub repositories, issues, projects, and other tools to plan and track your work, whether working on an individual project or cross-functional team.

In this guide, you will learn how to create and set up a repository for collaborating with a group of people, create issue templates and forms, open issues and break down work, and establish a project for organizing and tracking issues.

Creating a repository

When starting a new project, initiative, or feature, the first step is to create a repository. Repositories contain all of your project's files and give you a place to collaborate with others and manage your work. For more information, see Criar um repositório.

You can set up repositories for different purposes based on your needs. The following are some common use cases:

• Product repositories: Larger organizations that track their work and goals around specific products may have one or more repositories containing the code and other files. These repositories can also be used for documentation, reporting on product health or future plans for the product.
• Project repositories: You can create a repository for an individual project you are working on, or for a project you are collaborating on with others. For an organization that tracks work for short-lived initiatives or projects, such as a consulting firm, there is a need to report on the health of a project and move people between different projects based on skills and needs. Code for the project is often contained in a single repository.
• Team repositories: For an organization that groups people into teams, and brings projects to them, such as a dev tools team, code may be scattered across many repositories for the different work they need to track. In this case it may be helpful to have a team-specific repository as one place to track all the work the team is involved in.
• Personal repositories: You can create a personal repository to track all your work in one place, plan future tasks, or even add notes or information you want to save. You can also add collaborators if you want to share this information with others.

You can create multiple, separate repositories if you want different access permissions for the source code and for tracking issues and discussions. For more information, see Criar um repositório somente com problemas.

For the following examples in this guide, we will be using an example repository called Project Octocat.

Communicating repository information

You can create a README.md file for your repository to introduce your team or project and communicate important information about it. A README is often the first item a visitor to your repository will see, so you can also provide information on how users or contributors can get started with the project and how to contact the team. For more information, see Sobre LEIAMEs.

You can also create a CONTRIBUTING.md file specifically to contain guidelines on how users or contributors can contribute and interact with the team or project, such as how to open a bug fix issue or request an improvement. For more information, see Configurar diretrizes para os contribuidores do repositório.

README example

We can create a README.md to introduce our new project, Project Octocat.

Creating issue templates

You can use issues to track the different types of work that your cross-functional team or project covers, as well as gather information from those outside of your project. The following are a few common use cases for issues.

• Release tracking: You can use an issue to track the progress for a release or the steps to complete the day of a launch.
• Large initiatives: You can use an issue to track progress on a large initiative or project, which is then linked to the smaller issues.
• Feature requests: Your team or users can create issues to request an improvement to your product or project.
• Bugs: Your team or users can create issues to report a bug.

Depending on the type of repository and project you are working on, you may prioritize certain types of issues over others. Once you have identified the most common issue types for your team, you can create issue templates and forms for your repository. Issue templates and forms allow you to create a standardized list of templates that a contributor can choose from when they open an issue in your repository. For more information, see Configurando modelos de problemas em seu repositório.

Issue template example

Below we are creating an issue template for reporting a bug in Project Octocat.

Now that we created the bug report issue template, you are able to select it when creating a new issue in Project Octocat.

Opening issues and breaking down work

You can organize and track your work by creating issues. For more information, see Criar um problema.

Issue example

Here is an example of an issue created for a large initiative, front-end work, in Project Octocat.

Sub-issues example

Você pode adicionar subproblemas a um problema para dividir rapidamente partes maiores do trabalho em tarefas. Os subproblemas adicionam suporte para hierarquias de problemas no com a criação de relacionamentos entre os problemas. Você pode criar vários níveis de subproblemas que representam com precisão seu projeto, dividindo com exatidão as tarefas no nível de detalhe que você e sua equipe precisam. See Como adicionar subproblemas and Como navegar nos subproblemas.

You can use issue types to classify work in repositories across the organization, such as tasks, bugs, and features. See Managing issue types in an organization.

Task list example

You can use task lists to break larger issues down into smaller tasks and to track issues as part of a larger goal. Task lists have additional functionality when added to the body of an issue. You can see the number of tasks completed out of the total at the top of the issue, and if someone closes an issue linked in the task list, the checkbox will automatically be marked as complete. For more information, see Sobre as listas de tarefas.

Below we have added a task list to our Project Octocat issue, breaking it down into smaller issues.

Using labels to highlight project goals and status

You can create labels for a repository to categorize issues, pull requests, and discussions. GitHub also provides default labels for every new repository that you can edit or delete. Labels are useful for keeping track of project goals, bugs, types of work, and the status of an issue. See Gerenciar etiquetas.

Once you have created a label in a repository, you can apply it on any issue, pull request, or discussion in the repository. You can then filter issues and pull requests by label to find all associated work. For example, find all the front end bugs in your project by filtering for issues with the front-end and bug labels. See Filtrando e pesquisando problemas e pull requests.

Label example

Below is an example of a front-end label that we created and added to the issue.

Showing which issues are blocked by, or blocking, other work

By creating issue dependencies, you can easily see and communicate which issues are blocked by, or blocking, other issues. This helps streamline coordination, prevent bottlenecks and increase transparency across the team. See Creating issue dependencies.

Understanding new issues

When working on an unfamiliar or complex issue, GitHub Copilot can help you quickly understand the context, history, and key information, so you can get started faster and with more confidence.

Reviewing the issue

1. Navigate to an issue on GitHub.

2. No canto superior direito de qualquer página do GitHub, clique no ícone GitHub Copilot ao lado da barra de pesquisa.

   O painel do GitHub Copilot Chat é exibido. Para redimensionar o painel, clique e arraste a borda superior ou esquerda.

3. Se o painel contiver uma conversa anterior que você teve com o Copilot, clique no ícone de sinal de adição no canto superior direito do painel do Copilot para iniciar uma nova conversa.

4. At the bottom of the Copilot chat panel, in the "Ask Copilot" box, type a question and press Enter. For example, you could enter:

   • Summarize the main points of this issue
   • What’s the goal of this issue?

Copilot's summary will help you capture the purpose and scope of the work.

Understanding the history and comments

Issues often contain a history of discussions and decisions that can provide important context. You can use Copilot to summarize these conversations to identify key points, such as proposed solutions or unanswered questions. For example, you might ask Copilot to summarize recent comments or highlight decisions that have already been made. This helps you focus on what’s most relevant and ensures your contributions are aligned with the team’s priorities.

Clarifying technical terms

Issues often mention technical terms, code, or files that might not be immediately clear. You can use Copilot to get explanations or context for these references. For example, you can ask about the purpose of a file or function, or the meaning of a specific term mentioned in the issue. This helps you understand the details without spending extra time searching through documentation or code.

Getting suggestions for next steps

Once you understand the context of an issue, Copilot can help you figure out how to move forward. You can ask for suggestions on how to approach the work, like fixing a bug or implementing a new feature. For example, you might ask, “What’s the best way to resolve this issue?” or “How can I start addressing this problem?” Copilot's suggestions can provide useful starting points, helping you plan your work more effectively.

Making decisions as a team

You can use issues and discussions to communicate and make decisions as a team on planned improvements or priorities for your project. Issues are useful when you create them for discussion of specific details, such as bug or performance reports, planning for the next quarter, or design for a new initiative. Discussions are useful for open-ended brainstorming or feedback, outside the codebase and across repositories. For more information, see Comunicar-se no GitHub.

As a team, you can also communicate updates on day-to-day tasks within issues so that everyone knows the status of work. For example, you can create an issue for a large feature that multiple people are working on, and each team member can add updates with their status or open questions in that issue.

Issue example with project collaborators

Here is an example of project collaborators giving a status update on their work on the Project Octocat issue.

Using labels to highlight project goals and status

You can create labels for a repository to categorize issues, pull requests, and discussions. GitHub also provides default labels for every new repository that you can edit or delete. Labels are useful for keeping track of project goals, bugs, types of work, and the status of an issue.

For more information, see Gerenciar etiquetas.

Once you have created a label in a repository, you can apply it on any issue, pull request or discussion in the repository. You can then filter issues and pull requests by label to find all associated work. For example, find all the front end bugs in your project by filtering for issues with the front-end and bug labels. For more information, see Filtrando e pesquisando problemas e pull requests.

Label example

Below is an example of a front-end label that we created and added to the issue.

Adding issues to a project

You can use projects on GitHub to plan and track the work for your team. A project is a customizable spreadsheet that integrates with your issues and pull requests on GitHub, automatically staying up-to-date with the information on GitHub. You can customize the layout by filtering, sorting, and grouping your issues and PRs. To get started with projects, see Início Rápido para Projects.

Project example

Here is the table layout of an example project, populated with the Project Octocat issues we have created.

We can also view the same project as a board.

Next steps

You have now learned about the tools GitHub offers for planning and tracking your work, and made a start in setting up your cross-functional team or project repository! Here are some helpful resources for further customizing your repository and organizing your work.

• Sobre repositórios for learning more about creating repositories
• Mais informações sobre Projects for learning more about projects
• Alterando o layout de uma exibição for learning how to customize views for projects
• Monitorando o seu trabalho com problemas for learning more about different ways to create and manage issues
• Sobre modelos de problema e pull request for learning more about issue templates
• Managing issue types in an organization for managing issue types
• Gerenciar etiquetas for learning how to create, edit and delete labels
• Como adicionar subproblemas for learning about adding sub-issues
• Sobre as listas de tarefas for learning more about task lists