Project Management on GitHub

Introduction

Both git and GitHub have become indispensable tools in the lives of developers. Open-source projects can be saved and have their code shown in public repositories so that any developer can contribute by generating new functionalities or fixing bugs. Also, companies can save and version their code in private repositories and use the different tools that GitHub offers to improve their development processes.

Most companies and startups use agile methodologies to carry out the development of their projects. GitHub offers tools that allow us to manage our projects following the guidelines of agile methodologies. On the Internet there are also several tools with the same purpose. What’s the difference? Internet tools offer no integration with the code. Also, it is inconvenient for the developer to use one more tool/program outside of GitHub, and, likely, it does not have integration with GitHub or it is paid.

If we manage development within GitHub, developers will only have to use one tool and will be able to connect the code with the tasks assigned to them in the project.

In this article I will show the basics that GitHub offers to manage a project. I will use the Scrum methodology as an example and we will see a short tutorial on how to use these tools.

GitHub

GitHub calls itself a code storage platform for version control that facilitates collaboration in code development. The code of each project is stored in Repositories and offers us a variety of tools that will help us both in the development and the administration of the project.

Issues

In essence, issues are text entries that developers or anyone can create. Issues can be used to publicize a bug in the program, to describe upcoming features, or to describe user stories or tasks.
The latter is very useful if we want to manage our project with the Scrum methodology. epics, user stories, and tasks are important elements within this methodology. To create, describe, and manage these components, issues have the following characteristics:

Markdown

Markdown is a language mode for styling text, placing images and links. For a small glimpse of everything it offers us, you can go to the following site. The body of the issues is written with Markdown. So, in a simple way, we can place titles and subtitles, place a list of tasks, place external links that help explain a task or user story and in the same way place images.

Assignees

Within a repository, regardless of whether it is public or private, we can add people and assign these people to the issue. This allows us to have developers assigned to perform a task and the people who review the code or compliance with user stories.

Labels

Labels are keywords that are used to search between issues. They also provide essential information on the type of the issue, its content or the current status. We can place labels to differentiate the issues between epics, user stories and tasks. We can also place the importance of a task, or if it is a design or development task.

Projects

Projects are Kanban boards where we can add and manage repository issues. These help us to have an overview of the status of all user stories and project tasks. Later in this article, I will talk more in-depth about the projects.

Milestone

Milestones are issues grouped by a deadline or delivery time. These are very useful to have our user stories and tasks grouped in Sprints.

Issue linking

Another important feature of issues is that connections to other issues can be placed in the body. Each issue is identified with a unique correlative number. We can connect one issue to another by placing a # followed by the issue number (#17). With this functionality, we can connect a user story with all its tasks and vice versa, and it facilitates mobility between issues.

Linked Pull Request

Pull requests are a resource that is directly linked to development. When someone wants to add functionality to the main branch or some restricted branch, they need to make a pull request. This is so that CI/CD operations can be executed and the code can be reviewed before adding it to the branch. Pull requests can be linked in the same way that issues are linked in order to have a better follow-up of what is done in development.

With this in mind, we can now create our epics, user stories and tasks in such a way that it is easier for us to manage the project and for the developers to have a description of what they have to do. Now, we will see a small tutorial to create projects and issues in our repositories following the Scrum methodology.

Tutorial

Create projects

As mentioned earlier, projects are Kanban boards where we can add issues and see an overview of the status of all tasks. We will create a Scrum board to place all the user stories and another board to place the tasks of the current sprint.

To create a project we go to the main screen of our repository and go to the projects tab. There we click on the green button Create a project. Here it will ask us for the name of the board, the description and the template. First, we are going to create the Scrum board and give it that name. The description and template can be left blank.

The empty board will appear. The main elements of a Kanban board are the columns and the cards. The cards are placed inside the columns and passed from column to column, from left to right. In this board we are going to create the main columns of the Scrum methodology:

• Backlog: Here are all the repository user stories.

• Sprint Backlog: In the sprint planning, you choose which user stories are going to be done in the sprint. This column contains those stories and they are passed from the backlog.

• In progress: For user stories that are being developed.

• In review: For user stories that are currently in review.

• Done: For finished user stories.

These are the main columns, but depending on the company or organization, more columns can be added for testing or for more stages during development. We create those columns to have the base of our board.

Another special feature of projects is that adding or moving cards can be automated depending on whether an issue is opened or closed. In this case, we are going to automate the Backlog column with the creation of issues and the Done column with the closing of issues:

• Go to the three dots at the top of the Backlog column and click on Manage automation.

• Place the To do automation and mark Newly added.

• In the same way, we go to Manager automation of the Done column.

• Place the automation Done and mark Closed

Return to the main projects tab and create the board for the tasks. Here we are going to place and move the tasks of the current sprint with the following columns:

• Task backlog: Here we are going to place all the tasks at the start of the sprint.

• To Do: Here the Scrum master places the first tasks to be performed or the next tasks to be performed in the sprint.

• In progress: For tasks that are under development.

• In review: For the tasks that are in review.

• Done: For completed tasks.

In the same way, we place automation in the Task backlog column with the creation of issues, and the Done column with the closing of issues.

Create labels

As we saw before, labels are marks that help us to recognize and filter issues. This time we will only create three labels to be able to differentiate the issues between epics, user stories and tasks.

• On the main screen of the repository, go to the issues tab, and on the left side of the search bar, click on the labels button.

• Here we see the default labels of the repository.

• Create three labels: epic, story and task, with the colours you want.

Create milestones

The milestones help us to group the issues and place the date of which the milestone must be met. The issues can be the functionalities to be carried out for the next version and can be grouped in a milestone with the number of the next version and the release date. In another structure, the issues can be user stories and tasks and can be grouped in a milestone with the current sprint and with the end date.

This time we are going to create a milestone for our first sprint:

• On the main screen of the repository, go to the issues tab, and on the left side of the search engine click on the milestones button.

• Click on Create a Milestone.

• Place Sprint 1 in the title and add the due date and the description that you require.

Create Issues templates

We saw earlier all the features that issues have with which we can create epics, user stories and tasks. But, it can be a bit tedious to copy the same structure between different user stories or tasks. Luckily, GitHub allows us to have issues templates, in which we can create defined structures for these three types of issues.

On the main screen of the repository, go to the settings tab and go down to the issues section. There we see a button to create templates:

• In add template choose the custom template option.

• Click on Preview and edit and edit the template values.

• Let’s first create the template for the epic.

• Add the content and the epic label

-In the same way, we create a template for user stories and tasks.

• Finish and upload the changes to the master branch

Create epics, stories and tasks

Up to this point our workspace is created. We only need to create epics, stories and tasks, organize and assign them.

On the main page of the repository, go to the issues tab and create a new issue. A menu will appear with all the templates that we have created before.

For an epic we only need to put the title and description, we do not need to add an assignee or add them to a project.

For a story we place the title, link to the epic to which it belongs, add the description and tasks, assign the person in charge of following up on this user story and add it to the Scrum board.

For a task we place the title, link to the story to which it belongs, add the description, assign the person in charge of carrying out this task and add it to the task board.

After adding our epics, stories and tasks we can go to our boards and check that they have been added. In this way, at the beginning of Scrum, we can add all our epics and user stories to our project backlog.

In planning each sprint, we can pull the user stories to carry out, in addition to creating and adding their respective tasks to the task backlog.

Conclusions

What you have seen in this article are the basics to be able to manage a project on GitHub. From this, we can make improvements in our development process without leaving the platform where the developers work and where the code is.
If we want to improve this process even more, GitHub offers an API with which all the elements seen in this article can be created. By writing a script, you could automate the creation of epics, stories and tasks, the link between these elements and the addition to the different boards.

Personal boards

This scheme can be used in different situations, not only in open-source or agile Scrum development. A Topcoder member can use these elements to plan the challenges and competitions in which they are participating. Issues can be the tasks to be performed in a competition and can be grouped into a milestone that indicates the date the competition ends and boards can be used to organize these tasks.

Also, you don’t need to have a repository for each competition. You can create personal dashboards. If we go to our profile, we will be able to see the projects tab and there create one in the same way we did before. In this personal board, we can have all the tasks of our competitions laid out in a more orderly way.

What’s next?

This scheme can be taken to multiple developments simultaneously. If you have an organization, you can create a Scrum and sprint board that is for the entire organization and place all the user stories or tasks of all the developments that you have. In this way the overview of your entire organization or company will be in one place.

References

GitHub
Scrum
Markdown