A powerful tool for keeping track of tasks, enhancements, and bugs for your projects is the issues feature of GitHub. You can access the issues associated with a repository through the Issues tab.
They allow storing conversations about tasks in the project repository, visible to the whole team throughout the life cycle of the project, rather that them being buried in hard to navigate email chains! 💯
It’s also easy to see the status of tasks as issues can be closed when completed, leaving the tasks still pending visible by default.
You can write in markdown so they are great for having discussions around code.
They can also be assigned to a specific team member, labelled and associated with specific project milestones.
For more information, check out the Mastering Issues GitHub Guide
To organise the tasks for each team member, the owner will first open an issue for each person which will contain detailed instructions on how to complete the task.
I’ve actually used a nice feature of issues to make this easy for owners called GitHub Issue templates. The markdown files that power the feature are stored in the .github/ISSUE_TEMPLATE
folder of the project. Let’s see how they work.
For more information, check out Configuring issue templates for your repository in the GitHub Docs
To create a new issue navigate to the Issues tab
Click New issue
Because we are using GitHub Issue templates, we are immediately presented with the 3 issue templates I’ve created.
To demonstrate, I’m going to open the Add subtraction function issue. To initiate the process, I click on Get started next to the issue template I want to open.
You can override the templates and create an issue with custom content by clicking on Open a blank issue at the bottom of the page.
Because we’re working from an issue template, the title and contents of the issue are already pre-populated.
The contents of this particular issue contain detailed step-by-step instructions on how to add a subtract
function as well as a test to our pythoncalculator
package. At the top of the issue there’s also a checklist of all the steps involved which team mates can use to keep track of and communicate their progress.
The special -[ ]
list notation means the checkboxes will be interactive when the issue is submitted.
When we’re creating our issue, the main body contains two tabs:
Toggle the tabs below to explore this feature. Note how the checklist is rendered in the Preview tab.
Now that I’m happy with the content of the issue (which needs no editing…aren’t GitHub issue templates awesome?! 😜), I’m ready to assign the task to one of my team mates.
To do this, I click on Assignees on the top-right which launches a drop-down menu of team mates associated with the project and select the team mate I want to assign.
You can assign an issue to a team mate, add more or remove assignees at any point, even after you’ve opened the issue. If your repo is public, you can also assign issues to users who are not collaborators on your repo. Just type in their username in the drop down menu textbox.
Once I’ve assigned the issue to a team mate, I click Submit new issue to create it.
The issue has now been opened and given a unique number (in this case #2).
You can use the special #issue-number
notation anywhere in GitHub’s markdown (e.g. other issues, pull requests etc) to refer to it which will add a link to it automatically!
The issue is also now listed under the Issues tab.
Make sure you have opened and assigned a unique issue to each member of your team!
Now that tasks have ben assigned through issues, it’s time for team mates to get to work!
Let’s follow an example workflow by one of my team mates, bobturneruk, who will be tackling the add a subtract function issue I just opened and assigned to him.
Open the issue that was assigned to you and follow instructions within
subtract
branchMake sure to create a new branch to start work in!
To begin resolving the task, Bob first needs to create a new branch off the main
branch to work in. Before that, he checks that his local main
branch is in synch with the origin main
branch and that the main
branch is checked out.
If your local main
branch is behind the origin main
branch, click on Pull to pull the remote changes to your local main
branch.
Start by clicking the
Branch
button and giving the branch an appropriate name (subtract
).
The subtract
branch has now been created and been checked out (indicated by the fact that the the subtract branch in the local repository is now checked).
subtract.py
fileThe next step in Bob’s instructions is to create a new subtract.py
file in the pythoncalculator/
directory and paste the code for the subtract
function.
A nice feature of GitKraken Client is that, as well as a basic text editor, it also allows us to create new files!
To create a new file, first launch GitKraken Client’s Command Palette with
| Ctrl + P
Next, type File. This launches a dropdown menu of action you can perform on files. Select Create file.
For more information check out the GitKraken Client documentation on Adding a file and GitKrake’s Command Palette.
Next, type in the path to the new file you want to create, in Bob’s case it’s pythoncalculator/subtract.py
, and hit Enter|Return.
This creates the new file and opens it up for editing!.
Next, paste the function code provided in the issue instructions and save.
Please paste the code in exactly as it is in the issue instructions, even if you find something fishy with it 🧐
We now need to stage and commit the new file. Follow the steps we’ve been practicing and commit your file with an appropriate commit message (e.g add subtract function
).
Including the text resolves #issue-number-you-were-assigned
will link the issue to your pull request and automatically close it once your pull request has been merged! ✨ Find out more, including additional keywords you can use to link pull requests to issues
The file is now commited and we can see that Bob’s local subtract
branch is ahead of the origin and local main
branches by 1 commit.
pythoncalculator/__init__.py
fileNext Bob needs to add an instruction for the new subtract
function to be imported. To do this, he needs to edit pythoncalculator/__init__.py
.
To open pythoncalculator/__init__.py
, double click on it in the file finder panel.
To see all files in the repo, tick the View all files box. You can also initiate file editing through GitKraken Client’s Command Palette. More info on editing files.
Once the file is open for editing, add the import line of code from your issue to line 2 of the file.
Save, stage and commit your changes.
test_subtract.py
fileThe next step in Bob’s instructions is to create a new test_subtract.py
file in the tests/
directory and paste the code for the subtract
function test.
To create the new file, launch GitKraken Client’s Command Palette again with
| Ctrl + P
Next, type File to launches the file action dropdown menu. Select Create file and type in the path to the new file you want to create, In Bob’s case it’s tests/test_subtract.py
and hit Enter|Return.
Paste the code for the test provided in your issue.
Save, stage and commit your changes.
The final step of the process is to push the subtract
branch to origin and make a pull request to the origin main
branch.
To push the changes, click on
Push
and accept the default name to create the `subtract branch on origin.
Next, on the left-hand navigation panel, hover over PULL REQUESTS and click on the Create pull request button when it appears.
Configure the details of the pull request including the source and target repository (in this case your team’s copy of the repository) and the source and target branches. In this case Bob wants to merge the subtract
branch into the main
branch.
You can again include keywords, like resolves #issue-number-you-were-assigned
in your pull request Title or Description to link your pull request to your issue.
If you want, you can also add the owner as a reviewer but in the next steps, they will go through the review process anyways.
Finally, scroll to the very bottom and click on Create Pull Request to submit it.
The PR has now been created, as indicated by the symbol on the subtract
branch label.
Now it’s time for the project owner to review your contribution!