The GitHub Games Pt. 2 – Filing Your First Ticket

Before reading on, please read Part 0 and Part 1 of The GitHub Games series.
Assuming you have successfully signed up to GitHub as illustratively instructed in the first part of this blog post series, you are now all armed and equipped to venture into the GitHub ground to do whatever your heart desires. Just a few of the actions you can perform on GitHub include forking a repository, submitting your own code to a project via a pull request, and accepting community code contributions if you are a project maintainer yourself.

But none of those technical elements of this geeky social networking site (for GitHub is essentially a medium of networking for programmers) matter to us. As the end user, what concerns us is merely understanding the operation of the comprehensive issue tracking features of GitHub – filing a new ticket, searching among and commenting on existing issues, helping out in software testing by attempting to replicate reported bugs, etc. In this issue of The GitHub Games series, we’ll be filing our very first ticket on the tracker of the NVDA screen reading GitHub project. Before we galvanize into action though, let us review and introspect for a brief moment.

Why’d I Want to File A Ticket?

Any of what we are about to delve into and learn shall be fruitless if we deny ourselves an insight into what exactly it is that we are doing and the significance of this skill. Therefore, in order to truly appreciate this characteristic model of community participation unique to open source projects such as NVDA, let us get some context on this entire reflection.
How do you think does software development work? A group of programmers get their hands dirty and built the initial iteration of their software, but what happens then? In case of proprietory software, typically, the company behind the software confines a majority of the testing efforts to in-house quality assurance engineers and hired Beta testers, often excluding user feedback during its development cycle. However, in an open source framework, the users are the ultimate source of all bug reports, feature requests, and ideas about what works, what doesn’t, and how things can be changed for the better. As a user of an open source software such as NVDA, you have the influence to transmit your voice directly to the forces coding that software, by notifying them of critical bugs that you have independently identified, by proposing new functionality that truly takes NVDA to the next level, or simply by reducing the traffic through which developers have to rummage by testing, replicating and triaging issues filed by other users. All in all, if done correctly, you can exert your clout, if one may say so, in determining the progression of your favourite open source software.
Having established that, let us swiftly move on, shall we?

Steps

1. Ensure that you are logged in to your GitHub account.
2. Go to https://github.com/nvaccess/nvda/issues/new to straight get to the webpage containing the form for the submission of a new issue.
3. In case your focus is not already on the Title edit box, navigate to it and enter focus mode.
4. Here, you can enter a short title for the issue you are about to open that crisply summarizes the crux of your ticket. Some well-phrased and noteworthy examples of issue titles on NVDA’s tracker include “Skype for Desktop: Support for reporting spelling errors” (#6293), “Notepad: Pressing NVDA+B or attempting to use object navigation when pressing Alt+F4 after typing something results in dialog text repeating” (#6972), and “Word: Report ‘unsupported’ when pressing NVDA+V in browse mode” (#7297). Observe how clearly these issue titles communicate the essence of the contents of the ticket body.
5. With reference to the above examples, once you have inputted a reasonably explanatory yet succinct title for your issue, press Tab twice to move through the next controls, i.e. the Write and Preview tabs.
6. By default, the Write tab is selected, as a result of which the Comment body edit box is displayed in which the issue can be completely described. If you select the Preview tab instead by pressing Enter on it, this same edit box will be replaced by its output, i.e. a glance at what the contents of the Comment body edit box will show with Markdown taking effect.
7. Before you go any further, just know that Markdown is a way to style text on the web. Optionally, you may also want to read up on the syntax of this modest markup language in the context of GitHub by checking out this page.
8. Now, press Tab to move to the next form field, i.e. the Comment body edit box.
9. Here, you can empty the contents of that brimming brain with whatever feature you wish to request or bug you desire to report. But halt again, for this field is far from empty. What is all this?
10. Often times, to assist users in filing meaningful and structured tickets, developers and project maintainers add a template to guide users as to what all information is necessary for a proper diagnosis and assessment of the ticket. In the case of NVDA’s tracker, the Comment body is divided into five sections, namely Steps to reproduce:, Expected behavior:, Actual behavior:, System configuration:, and Other questions:. Having said that, what you must bear in mind is that you aren’t bound to furnish all the required information, and can even erase all the default contents of this field and thus not respect the template, and describe your bug or feature idiosyncratically. While the template is advisory in nature, you are nonetheless strongly recommended to adhere to it for an optimal experience.
11. Once you have perused the template, begin deleting all extraneous lines starting with “> ” in order to do away with hints only meant for your benefit but which would otherwise clutter the complete ticket.
12. In their place, enter the steps required to replicate the discrepancy you are experiencing, followed by the behaviour you expected NVDA to exhibit, and what actually happened contrary to your expectations. Do add detailed system configuration related information, and conduct the required testing before answering the final few questions. Strive to retain the original format of the template, as far as possible. Also, it always helps to provide compelling real world usage cases when proposing a new feature, or elucidating the basis for your expectation when the correctness of a behaviour is disputed while reporting a bug, etc., but even if you fall short of providing adequate data in some respects, most developers, especially those of NVDA, are patiently willing to engage with and gently poke you for clarifications. You may refer to not only the issue titles but also the ticket bodies of the three issues cited previously to build a basic understanding of a typical ticket.
13. When you are satisfied with the body of your ticket, press Tab to move to the next form field, i.e. the Attach files to your comment button.
14. Here, you can attach files by dragging & dropping, selecting them, or pasting from the clipboard. Such a situation would only arise if the nature of your ticket demands a specific test file or sample document for others to reproduce what you are talking about to be on the same page, or if a log file is requested by a developer to support your bug report (see LogFilesAndCrashDumps for details).
15. Press Tab two last times to move to the last form field, i.e. the Submit new issue button.
16. Bang the Enter key and rejoice in the fact that you just successfully finished filing your very first ticket on GitHub!

Remarks

• If you disliked my initial overindulgence in providing the direct link to the New Issue form, following were the steps taken to get to this destination:
  1. Go to the GitHub project page of the software pertaining to which you want to report issues, https://github.com/nvaccess/nvda in case of NVDA.
  2. On this page, locate and activate the link that reads “Issues{number of open issues}”, Issues1,963 link in case of NVDA at the time of writing this blog post.
  3. On the page that subsequently loads, locate and press the New issue button to get to the same destination the long but arguably proper way.
• While many GitHub-based issue tracking systems offer a template, there are many that don’t as well, leaving the Comment body or an equivalent edit field blank.
• Once you have created an issue, submitted a problem, or filed a ticket – all phrases are more or less synonymous to each other and may be used interchangeably – you will not receive an e-mail notification for the same. However, you will be constantly updated about any subsequent comments made or actions taken by others on a ticket that you have authored via e-mail.