Issues on a GitHub repo are a great way to track the things you need to fix, add, or change. When you combine issues with project boards, you get insights into your project that would otherwise be hard to track. In this section, you create issues and project boards and change your README.md.
1. Creating a project board and an issue
To get started on issues and project boards, go to your repo on the Code tab and then follow these steps:
- Click the Projects tab and then click the Create a project button.
The Create a new project dialog box appears, as shown in Figure 3-15.
- Add a project name and description.
- From the preloaded Template drop-down list, select a project template and click the Create project button.
In this example, I chose Automated kanban as my project template.
A project board appears with some To do cards to show you how things work (see Figure 3-16).
- Click the Manage button at the bottom of the To do column to open the dialog box to choose what automation should happen.
Figure 3-17 shows the automation settings for the To do column. Every time an issue gets created, it is automatically added to your To do column. You create an issue in Step 8 of this section.
- Click the Manage button at the bottom of the In progress column.
A similar automation settings dialog box appears (see Figure 3-17). Every time an issue is re-opened after you close it, or a pull request is created or reopened, it appears in the In progress column. You see this card in the To do column if you revisit the project after Step 11 of this section.
- Click the Manager button at the bottom of the Done column.
Similar to Figure 3-17, automation settings appear. Every time an issue or pull request is closed or a pull request is merged, the cards move from the previous columns to this column. You see this in Step 14 of the section “Closing an issue”.
You can change the automation settings for these columns or add other columns. Check out https://help.github.com/articles/configuring- automation-for-project-boards for more information on project board automation.
- Delete the cards that were automatically added to the To do column by clicking the three dots on the top right of each column and choosing Delete note from the drop-down menu that appears.
The card disappears. You can then click on the three dots of the next card that was automatically added to delete it.
- On the Issues tab, click New issue.
If you haven’t previously dismissed the dialog box, Figure 3-18 shows the dialog box that appears above the Issues tab. Issues and pull requests can have labels, which are useful when you’re trying to sort through things that still need to be done. If you’re going to contribute to an open source project, looking for help wanted or good first issue labels is a great way to get started in the community. (see Part 5 for more information on open source software).
- Add a title and description to the new issue and then, on the right side, assign yourself to it.
- Link this issue with a project by clicking Projects and choosing Tracking Changes to HelloWorld.
After you choose it, you see it in blue under Projects, as shown in Figure 3-19.
11 Click the Submit new issue button.
Just like with the pull request, the issue has a title, number, status, description, and some metadata on the right side (see Figure 3-20). One interesting bit of information is that the number is #2 for this issue, even though it’s the first issue you’ve created on this repo. That is because issues and pull requests follow the same numbering, so the pull request was #1, this issue is #2, and any pull request or issue you open next will continue with #3.
After you create an issue, the card relating to it appears on your project board.
To see the new card in the To do column, click on the project board link under Projects.
2. Closing an issue
The best way to close an issue is to create a pull request with changes to address what was written in the issue. Understanding the relationship between issues and pull requests can help you on your own projects and open source projects.
To close out the issue, follow these steps:
- From the Code tab on your repo, click the pencil icon for the README.md file to edit the file.
- Add a section at the bottom of the README.md file with your favorite books.
- Scroll to the bottom of the page and add a title to the commit.
- Choose Create a new branch for this commit and start a pull request.
- Click Commit changes.
- Add a description to the pull request.
Specifically, make sure that you write closes #2 on its own line. When you type #, GitHub suggests any issue or pull request that you have in this repo to auto-fill.
- Link the project to this pull request.
You link the project to the pull request the same way that you link a project to an issue. (See step 10 in the section “Creating a project and an issue”, earlier in this chapter.)
- Click Create pull request.
- Return to your project board.
You see the card for the pull request in the In progress column, as shown in Figure 3-21.
10. Click the pull request card title to preview the pull request.
Click Go to pull request for full details to return to the pull request.
11. Click the Files changed tab and then click View file.
You see the README.md file with your last section added (see Figure 3-22).
12. Click the Back button on your browser.
13. If you’re happy with the changes, click the Conversation tab, click Merge pull request button, click Confirm merge button, and then click the Delete branch button.
You can revisit the section “Merging a pull request,” earlier in this chapter, for more details on how to complete this step if you get stuck.
- Click the Projects tab and choose the project that you created.
Both of the cards have moved from the To do and In progress columns to the Done column.
Source: Guthals Sarah, Haack Phil (2019), GitHub for Dummies, Wiley.