Working with GitHub issues

What is GitHub and why use issues?

GitHub is a web platform where people collaborate on projects. GitHub issues are like discussion threads where people can:

Report problems or bugs
Suggest improvements
Discuss ideas

The W3C Internationalization Activity uses GitHub issues for technical discussions. This page provides an introduction to working with issues for those who are new to GitHub.

The first thing to say is that working with GitHub issues is very easy and intuitive! GitHub can occasionally involve complex behaviours when dealing with software or document change management, but there is nothing complex about working with GitHub issues. If you can use email or comment on a blog post, you can use GitHub issues!

Do I need an account?

To view issues: No account needed! You can read all discussions without signing up.

To comment or create issues: You'll need a GitHub account.

To create an account:

Go to github.com
Click the "Sign up" button
Choose a username, enter your email, and create a password
Verify your email address when GitHub sends you a confirmation

That's it! You can start participating in discussions immediately.

Finding and viewing issues

Step 1: Navigate to the Issues tab

Each GitHub repository (project) has a prominent link to its issues. A repository is like a project folder that contains all the files and discussions for a particular topic.

The picture below shows the home page of the repository for the Japanese Layout task force. The blue circle shows where to click to get to the issue list.

Step 2: Browse the issue list

After clicking on that tab, you will see a page like this, which lists all currently open issues.

Screenshot of GitHub issues list page showing multiple open issues with titles, labels, and metadata

Understanding the issue list:

Open issues are active discussions (shown by default)
Closed issues are resolved or completed discussions (click "X Closed" to see them)
Labels are colored tags that categorize issues (like question or bug)

You can filter the list by clicking on labels or using the search box at the top.

Step 3: Read an issue discussion

Click on any issue title to view the full discussion thread. For example, here's what you'll see if you click on the 3rd title in the above list.

Diagram showing parts of the github setup.

This page works like a forum thread or email conversation - you can read all the comments from top to bottom.

Adding comments to an issue

To add a comment to an issue, simply start typing into the box at the bottom of the thread (see the picture just above).

If you like, you can add markdown to the text or click on the icons to add formatting to your comment.

When you are done, check your comment using the Preview tab, and then simply click on the Comment button.

Note that GitHub will treat angle brackets in your comment as HTML markup, so if you want to include examples of source code, you should put reverse quote (`) characters around them.

Also, if you want to reply to a particular sentence or paragraph earlier in the thread, copy that to your comment and put a greater-than sign (>) at the beginning of the line. GitHub will then give that text a grey background.

You can experiment with the icons above the input box to discover other editing aids.

Following a discussion

If you contribute a comment to an issue, you will automatically be subscribed to that issue and will therefore receive email notifications as new comments are added.

If you haven't contributed a comment, GitHub provides the Subscribe button (which notifies you of changes to this particular issue only), or the Watch button at the top of the page (which notifies you of changes to any issues in the repository, as well as pull requests).

You should, however, also consider subscribing to the mailing list for the repository you are following. That mailing list should be indicated in the explanatory text on the repository's home page. When subscribed to that list you will receive a (single) daily digest containing links to all issues in the repository that have changed over the past 24 hours. But the digests will also point you to related issues in other repositories too (such as CSS and HTML repos).

Creating a new issue

Anyone can raise a new issue. Simply click on the New issue button, add a short but meaningful title, and write your comment in the box provided.

Picture of a new issue awaiting input.

Only people with administrative access are able to assign labels to an issue. They will be notified that you have created a new issue, and will decide which labels to assign to it.

Etiquette & tips

Please bear in mind the following:

Think over your comments before you write, and check them before submitting. Try to keep them as clear and succinct as possible.
Always keep to the topic of the thread. If there are other things you want to bring up, raise additional issues. The aim should be to keep each thread focused on a specific topic.
Always remain polite and constructive in your comments.
You can attract someone's attention, even if they are not following this issue, by including an @ sign followed by their github id, eg. "@r12a what do you think of this idea?".

Glossary

Repository (or "repo"): A project folder containing all files and discussions for a particular topic or project
Issue: A discussion thread about a specific topic, problem, or suggestion
Label: A colored tag that categorizes issues (like "bug", "question", or "enhancement")
Markdown: A simple way to format text using symbols like * for bold and > for quotes
Mention: Notifying someone by typing @ followed by their username
Fork: Making your own copy of a repository (not covered in this guide - used for code contributions)