Chapter 1
For this purpose, let's create two more issues. Next, head over the Issues page, select
the boxes of the issues that you want to assign, and select an assignee, as shown in
the following screenshot:
After selecting the assignee, the issues will immediately get updated with the new
are assigned to:
Each issue can have only one assignee.
[ ]
Brief Repository Overview and Usage of the Issue Tracker
Labels
If you have worked with WordPress, labels are like tags. This is not to be confused
with Git tags, though. We will explore how to create labels and use them effectively
to easily categorize batches of issues.
Labels provide an easy way to categorize the issues based on descriptive titles such
as bug, feature, and any other words you feel like using. They have colors and are
visible throughout the issue tracker or inside each issue individually.
to visualize only the issues you are interested in. Let's see how that works.
Creating new label names and setting different
colors
Head over the issue tracker and navigate to the label page by clicking on Labels,
as shown in the following screenshot:
The name and the color are fully customizable for new and existing ones.
[ 20 ]
Chapter 1
Creating a new label is as easy as pressing the New label
name, and choosing a color. In fact, a random color is already picked, so the only
prerequisite is the name. I have created a new yellow label named ,
as shown in the following screenshot:
Immediately, the label is created and it appears in the list. Back to the issues, let's
on the gear for the
dropdown to appear. Start typing to narrow down the search.
[ 21 ]
Brief Repository Overview and Usage of the Issue Tracker
As you might have guessed, you can choose more than one label in an issue. After
you choose them, just click anywhere out of the label window to save the action.
Immediately, you see the changes:
Notice how GitHub makes note of any change made to the issue. This way, you
[ 22 ]
Chapter 1
As with the assignees, you can also mass-assign labels to issues. Let's try this by
going to the main issues page and selecting some issues; then, choose the bug label:
The issue tracker gets updated and now you can have an overview of the issues with
the labels assigned to them:
[ ]
Brief Repository Overview and Usage of the Issue Tracker
Suppose you have 100 opened issues, many labeled as bugs. Wouldn't it be cool
clicking on the bug label, GitHub basically makes a query and, as a result, only the
Back to the Labels page, you can see that one can have an overview of the number of
issues assigned to each label:
Milestones, much like labels, are primarily used to group issues, but for different
purposes. Consider a milestone like a special label that has a title, a description,
and an optional due date.
Why milestones are a great help when working with
code versioning
It is common knowledge that applications are released in versions. From the
BIOS of your laptop to the web browser you use to explore the Internet, they
all use versioning.
Many companies, or even community-driven open source projects, tend to have a
road map that dictates the time the new product will be released to the public.
GitHub integrates this feature with the issue tracker. Let's dive in and learn how to
create a new milestone, attach issues to it, and use the overview to see what issues
remain resolved or unresolved.
[ ]
Chapter 1
Creating a new milestone
While at the main page of the issue tracker, click on the Milestones link, next to the
Labels link. If no milestone has been created yet, you have two buttons that create
a milestone. Generally, the New milestone button will be the main one to use,
as shown in the following screenshot:
Now, let's
The Description and Due Date
it looks like, let's add all the information:
[ 25 ]
Brief Repository Overview and Usage of the Issue Tracker
After you create it, it will appear in the Milestones page with all the information we
previously entered:
On the left-hand side, there is the name, the due date, the description, and a note of
the time it was last updated. On the right-hand side, you can see the percentage of
completion and the number of open and closed issues. Of course, you can edit, close,
or delete it completely.
Adding issues to milestones
Now that we have at least one milestone, let's add an issue to it.
Again, there are two ways to add a milestone to an issue. Much like assignees and
labels, you can do this inside each issue or mass-add it when in the issues main page.
[ 26 ]
Chapter 1
After selecting the milestone, the page will be refreshed and the issue will now be
added to the selected milestone. If you watch carefully, you can see a small icon and
the name of the milestone next to it:
or are yet to be resolved
When dealing with hundreds of issues, bug reports, and enhancements, it is nice to
have an overview of what is resolved and what is not.
Let's add another issue to the milestone and immediately close it, marking it
as resolved. Head over the milestones page and see that the bar is now half full
(at 50%):
Tips and tricks
The are essential for your project as they add useful information to the
The
automatically shown on the front page of your repository, so it is always a good idea
[ 27 ]
Brief Repository Overview and Usage of the Issue Tracker
GitHub checks whether the
for rendering, it automatically gets formatted according to its implementation.
For example, a extension that stands for markdown,
that stands for restructured text, that stands for AsciiDoc, and so on.
If the extension is
formatting is done.
For a list of supported markups, go to
.
Navigating easily with keyboard shortcuts
A nice feature that
with all the supported shortcuts for that particular page. To see all shortcuts,
click on the Show All link.
Summary
project's bugs, feature requests, and so on. Moreover, you learned how to use labels
and milestones to better group the issues.
In the next chapter, we will learn about wikis as well as GitHub's feature about
code release.
[ 28 ]
Using the Wiki and Managing
Code Versioning
create as many pages as you like and also grant public access to it so that everyone
can edit it.
In addition, when you are the creator of a product and have users that rely on it, you
will want it to be as stable as possible. Versioning helps to maintain an achievable
goal. GitHub provides the right tools to release versions of your code, which in
reality are just snapshots in time. Whenever you believe your project is ready to get
releases feature and deliver versioned tarballs to the world.
by providing a home for your documentation that will complement your project.
accompanied with optional release notes. This way, the end user can understand
the changes from any previous versions.
create a new repository, a wiki attached to this project is also created.
It is enabled by default and everyone can add new content or modify existing
pages. If you want to change this behavior, refer to Chapter 6, Exploring the User
and Repository Settings, which shows how to accomplish this.
[ ]
Using the Wiki and Managing Code Versioning
Why wikis are a nice place to document your
project
Documentation is not to be taken lightly. To paraphrase a famous quote: "With great
projects comes great documentation."
HTML, you may not want to use an external page to host your documentation.
Enter GitHub wiki.
Create a new wiki page
From the right-hand side bar, select the wiki tab (the one with the book icon) in order
to head over the wiki. Since our wiki has no content yet, there doesn't exist any page.
Go ahead and hit the green button.
[ ]
Chapter 2
Every time you add a new page to the wiki, the process is the same. At the top, there
this is also used to form the URL from which you will have access to the page:
[ ]
Using the Wiki and Managing Code Versioning
Home by default. Even if you pick another name, the Home page
is created automatically and is used as the front page of your
wiki. The name behaves in a way like does for
repositories, and it cannot be deleted.
Below the title area, there are two tabs. When the Write tab is active, you can begin
to write in the blank area below. In case you choose to write in a markup language,
the Preview tab renders the text and shows how it will be presented when you save
the page.
Below the title, there is a nice toolbar that has the most common actions such as
headers, bold text, italics, and lists. At the time of writing this book, GitHub supports
nine markup languages to choose from. Pick one from the Edit mode drop-down
list and the text will be rendered accordingly. For every language you pick from the
menu, there is a little help page with the most common actions. Hit the question
mark icon to see the help area.
Finally, when you are ready to save the page, you can provide a short message
describing what the changes were about. Consider it like a Git commit message.
Later, when we explore a page's history, the edit message will come in handy.
Whenever you are ready, press the Save Page button and the page will be created.
Deleting a page
Every page except Home can be deleted. In order to do this, go to the page you want
to delete and hit the Edit button at the right corner. As we will see later, deleting a
page does not necessarily mean that it is purged forever. Read ahead and learn how
to undo things.
[ ]
Chapter 2
While GitHub supports multiple markup languages, we will explore Markdown as it
is the most well-known one.
Let's create another page, namely , with some content as follows:
[ ]
Using the Wiki and Managing Code Versioning
I have used several Markdown elements, and hitting Preview will show you how
the page will be rendered when it is saved. After you hit Save Page button, the new
Installation page will look like the following:
Some elements worth mentioning are the links. There are two kinds of links: external
and internal. External ones are written by giving the full URL including the FQDN,
whereas internal links only get called with the page name.
with , such as , and you can also put some random
text such as . Inside
the brackets, you can put any text you want, followed by the actual link inside
parenthesis. Be careful to not leave any spaces between the second bracket and the
Internal links are useful when you want to link to another page of your wiki. Imagine
to refer to another page. GitHub implements MediaWiki's markup in that case. Use
double brackets and inside it, put the name of the wiki page you want to link
to. In our example, I used and this will create a link to another
page. Notice that if the link does not exist, it is rendered in red color. If you click on
it, you will be redirected to create the page.
[ ]
Chapter 2
When creating headers, you use before the text. The number of
style that will be used. Each header gets a separate anchor link, which you can see if
you place your mouse over it on a saved page. This anchor link can then be used to
reference internal links.
In our example, you can see that I created three headers namely ,
, and . In , I placed an interlink
with a reference to . The piece of markdown that did this is
. This style introduces two new
areas to explore.
Firstly, you can see that an alternate text can be used much like with external links.
The only difference is that both the alternate text and the link are placed inside the
double brackets separated by a pipe ( ). Secondly, you can see how the call to the
sign ( ) and last is the header. It is important to understand that the header as part
of the interlink gets transformed, where empty spaces are replaced with hyphens ( )
and all special characters ( , and so on) are lost.
rendered correctly.
link to another wiki with an internal link. In this case, you will have
to use external links.
it in the nice cheat sheet at
.
If you have write access to a wiki, you should be able to see the Add a custom
sidebar and Add a custom footer buttons.
GitHub has a default sidebar where it places all the pages of the wiki. This might not
be useful since they are shown in name order and sometimes you want users to be
able to access the important information without searching too much.
[ ]
Using the Wiki and Managing Code Versioning
Much like any other wiki page, the sidebar can be written in a markup language that
GitHub supports. In the following example, I used Markdown:
As you can see, I used a bulleted list and links on each item. Indenting an item (one
or more spaces) will provide the following result:
[ ]
Chapter 2
Like sidebar, you can also create your own custom footer. For example, I used two
external links with a custom text, as you can see in the following screenshot:
After all get a nice wiki page with our custom sidebar and footer:
[ ]
Using the Wiki and Managing Code Versioning
Watching a wiki page's commit history and
reverting to a previous state if needed
Would you be surprised if you were told that a wiki is essentially a separate Git
Tips and tricks section, we will see how to clone a wiki locally,
make changes, and push back to GitHub.
As with all Git repositories, there are commits and a history log. Each page gets a
the history log is to click on the revisions link on each page. This can be found under
each page title. Take, for example, the Home page:
A link to Page History can also be found when you edit a page.
One other way to see the history log is to append to your
page. So, for example,
becomes
.
Here is what my Home page log looks like:
[ ]
Chapter 2
From the
history table.
In this example, there is only mine, but in a wiki with many collaborators, you can
easily tell who made what change. Then, you get the commit message that is super
useful because you can tell from a glimpse what the change was about. The third
of the change.
custom ones since they follow the pattern
. Where language the
markup language that was used to create the page.
Now, let's use the power of reverting when things go south. Firstly, create a new
it is no longer there, so head over the main History page of all pages.
In order to revert things, you need to use the Compare Revisions
choose between one or two revisions to revert from:
Here we chose two, but since they are one after another in the commit history,
choosing only the last one would be the same. It's like comparing the changes
between and , where is the last
commit and is the one before it. The is the same.
[ ]
Using the Wiki and Managing Code Versioning
After hitting the button, we will see the change that was
introduced with this commit:
Let's bring back the deleted page by hitting the Revert Changes button. At the time
of writing, every time I tried to revert the deletion of a page, I was presented with
500 internal server errors. Despite the error, go back to the History page, and you
will see that the revert was indeed performed and the deleted page was brought
back from the grave:
With blue mark, you can see the last commit where the page was deleted and with
red mark, you can see the previous one where the page was created.
Sometimes, you will not be able to compare any two revisions
with a message:
This patch was not able to be reversed.
That's all there is about GitHub wikis. Next we will focus on managing code releases
with the tools GitHub provides.
[ ]
