10Collaborative working

GitHub has a rudimentary issue tracking mechanism built into it. It allows issues to be categorised with labels and assigned a completion date (milestone).

I will demonstrate the use of issues from the practicalseries-lab profile using the lab-01-website repository.

From the lab-01-website repository home page, click the issues tab:

Figure 10.24   Repository home page issues tab

This takes us to the open issues page:

Figure 10.25   Open issues

To create, edit and delete labels click the labels button (highlighted above):

Figure 10.26   Label edit page

Clicking the delete button on the right hand side will delete the associated label (there is a confirmation box).

The edit button allows the text and colour of the label to be changed.

The new label button creates a new label; use it to create a proofreading label:

Figure 10.27   Create a label

Enter the required label name and click create label to add it to the list.

Milestones just mark specific dates with an identifying name that can then be attached to an issue.

To create a milestone, click the milestone button next to the label button on either the issues page (Figure 10.25) or from the label page (Figure 10.26).

Figure 10.28   Milestone page

Click the new milestone button to add a milestone:

Figure 10.29   Create milestone page

Add a title (Release 01 in this case)—note: milestone titles must be unique, enter a description and give it a date from the calendar. Click create milestone to create it. This will show the new milestone on the milestone page:

Figure 10.30   Populated milestone page

Click the issues tab to open the issues page, Figure 10.25.

Click the new issue button to open the create issue page:

Figure 10.31   Create issue page

This is fairly straight forward, give the issue a title and add any comment you feel is required. I gave it the title README.md - add getting started section.

To assign a user to the issue and to assign labels and milestones just click the relevant cogwheel (highlighted) and choose what you want from the dropdown list.

To create the issue, click the submit new issue button. This will take you back to the issue page (Figure 10.32):

Figure 10.32   Open issues page

This is just a record of what we did when we created the issue.

There is one thing of note here; the #number at the top (highlighted), this is the issue number and it’s already at 4—“but why, this is the first issue?” you say.

The answer is: because pull requests are also part of the issue numbering mechanism and there have already been three of these (one for the simple branch merge, one from the branch merge with conflict and one for the forked repository pull request).

This number is useful; we can use it to close the issue from a commit.

Any issue can be closed from the issues page:

Figure 10.33   Directly closing an issue

Just give a reason in the comment section and click the close and comment button. This will close the issue.

Let’s assume we didn’t close the comment in the previous section and it’s still open; let’s also say we want to make the modification suggested (add a getting started section).

Go back to the repository home page, open and edit the README.md file and add the following:

Figure 10.34   Closing an issue from a commit

I’ve added lines 17, 18 and 19 to the README.md file.

I’ve also added a commit message and an additional comment.

The thing to notice is that in the commit message I’ve added the text closes #4. This is an inline command and it tells GitHub to close the #4 issue, this was the issue we created in Figure 10.32, the number is at the top, highlighted.

Click commit changes.

Go back to the issues page; the issue will now be closed so go to the closed issues tab and click the issue itself:

Figure 10.35   The closed issue

The issue is closed, and the commit number that closed it is shown: [780b895].

Note also that the milestone has been completed, this is because the only issue associated with the milestone is complete (hence the milestone is too).

The inline command closes is not the only command that can close an issue, the following all do the same:

close closes closed fix fixes

fixed resolve resolves resolved