This document is a brief tutorial on using GitHub for issue tracking.
GitHub comprises several components. The original and most well-known component is the Git software repository. Other components include:
This document covers the GitHub issue tracker. It does not require any knowledge of the Git software repository. The issue tracker is accessed from the web-based interface to GitHub.
First step is to create an account on GitHub. You can use an existing account or create a new, free account. It is recommended to use an account that is not tied to your current employer. Personal accounts are free.
Note: Personal accounts are not free if the account is used to reate private repositories in that account.
Note: The GitHub account for SMPTE can and should be used to create private repositories at no charger to the user.
Navigate your web browser to GitHub. Even if you already have an account, you will probably see the dialog box for creating a new account. There are three fields:
and a large green button to “Sign up for GitHub”. If you already have an account, there is a small button to “Sign in” in the upper right corner of the webpage.
The dialog box for creating a new account is so prominent that experienced GitHub users often fill in that dialog box only to get an error message saying the that username is already taken.
You will receive a confirmation email from GitHub almost immediately. Follow the instructions in that email to finalize creation of your account.
Your username is important and cannot be changed. The email address can be changed later. The “Sign in” dialog box allows you to login using either your username or email address. You will probably find it easier to use your username as it will most likely be shorter.
Second step is to become a member of the SMPTE organization so that you have access to the private repositories used for SMPTE projects. Send an email to Mauricio or anyone with administrative access. GitHub organizations allow a user to access repositories for different companies. For example, you can use one account to access repositories that belong to SMPTE, your company, any companies for which you are a consultant, other standards organizations, and your personal repositories (which is the default).
You will receive a confirmation email from GitHub almost immediately. Follow the instructions in that email to finalize your membership in the SMPTE organization.
The upper-left corner of the GitHub web page has a pull-down menu that allows the user to select the account for subsequent operations. The choices include: * Your personal account (indicated by the display of your GitHub user name) * The SMPTE organization (indicated by the SMPTE logo and name) * Other organizations you are a member of on GitHub (for example, your company)
For the purpose of issue tracking, it does not matter whether you select your personal account of SMPTE, but selecting SMPTE narrows the display on the left side of the window to only SMPTE repositories.
After creating an account and joining the SMPTE organization, you are ready to join the teams associated with one or more repositories.
Send an email to the administrator of the repository to request access to the corresponding team. This will give you access to all repositories in that team.
Typically the team administrator is the chair of the corresponding SMPTE group.
Now that you have a GitHub account, have been granted access to the SMPTE organization, and have joined one or more teams, you are ready to get to work.
Go to the SMPTE GitHub website and log in using your personal GitHub account. You may already be logged in as GitHub remembers your login for several weeks, assuming you logged in using the same browser from the same platform. If you need to login, you will be directed to the login page. Remember to use the “Sign in” button in the upper right corner of the page, not the dialog box for creating a new account.
After you are logged in, you will see a pulldown menu in the upper left corner with your GitHub username. Use the pulldown menu to select the SMPTE organization. This is not necessary, as you will be able to access the repositories for all organizations that you have joined, but will make it easier to see all SMPTE repositories. After selecting the SMPTE organization, select “View organization” in the upper left corner to see all repositories. The list of repositories can be narrowed by using the search box at the top of the page.
Select the repository from the list on the left.
After you selected a repository, you will be in the “Code” view, which is useful if you are developing software, but not necessary if you only want to work with GitHub issues.
Select the “Issues” tab in the toolbar near the top of the page.
You will be able to see all issues and can use the Filters pull-down menu to control what issues are viewed. For example, the Filters menu allows you to see only issues assigned to you. By default, the filter is set to display only open issues.
When you try to create an issue, you may be directed to a page that lists one or more issue templates. If one of the issue template seems applicable, select it; otherwise select “Open a blank issue.” Not all repositories have issue templates. Templates are added to each repository by the administrator and seed the report with predefined text and instructions on how to complete the report, much like a SMPTE standards document template.
If you choose “Open a blank issue” or if the repository does not have any issue templates, you will be directed to fill out a blank issue. (See section Basic Issue Reporting, below).
To create a new issue, select the green button on the right:
An example of basic issue reporting without a template is shown in Figure 1.
Do not worry, at first, about the assignee, label, projects, and milestone options on the right. That information will be filled in later by the administrator of the repository.
GitHub uses markdown, but you do not need to know markdown to use the tools in the toolbar. However, if you know some basic markdown commands, it can make filling out the form easier.
See section Issue Guidelines below for advice about writing good bug reports and feature requests.
The procedure for filling out a report starting from a template is the same as for non-template reporting (see section Basic Issue Reporting, above). The template may guide drafting the report with pre-defined sections and instructions. An example of starting a new issue in a repository that has defined an issue template is shown in Figure 2.
Since GitHub uses markdown, the template will contain markdown formatting but you can still use the formatting tools in the toolbar.
See section Issue Guidelines below for advice about writing good bug reports and feature requests.
The key principle in writing good bug reports is to describe how to reproduce the problem: 1. What is the expected behavior? 1. What is the behavior that was observed? 1. How does the actual behavior differ from the expected behavior? 1. Why is the difference important, 1. What are the detailed steps to reproduce the problem?
If possible, the bug report should include screenshots that illustrate the problem. Very helpful if the bug report includeds input data so that the developer can run the data to see the problem in a debugger.
The key principle in writing a good feature request is to justify why the feature should be implemented: 1. How does the software currently work? 1. How should the software work differently? 1. Why is this new behavior required by a typical user?
The best advice on drafting comments against documents is to follow the practices in writing ballot comments on Workspace: 1. Short description of the issue, 1. Summary of the problem, 1. Location of the problem, 1. Recommended changes.
The overall process for handling issues may vary with the group but typically the report starts out in the backlog, is moved to active when a developer begins work on an issue, then moved to review when the developer has finished working on the issue. Finally, the issue is closed after it has been completely addressed.
The group may choose to use a project board such as the one shown in Figure 3.
For document issue tracking, the process would be simliar to software or ballot comments. The issue must be fixed or rejected and, if fixed, the change should be reviewed by the originator of the issue.
For more information, send an email to the Software Task Force.