Chapter 2
In the world of software management, almost every piece of software is shipped
with a version. It is a way to declare its evolvement through time; usually with
provides a simple interface to ship your versioned software.
Creating a release
In GitHub, the
tags, if any, from the same menu where you change a branch, as shown in the
following screenshot:
If you visit the Releases page and there is no tag created yet, you will be prompted
to create one. Creating a release will automatically create a tag.
[ ]
Using the Wiki and Managing Code Versioning
Let's click on the Create a new release button. The following page will appear:
Tag version box, everything else is optional.
If the tag name you provide already exists, you will be presented with a duplicate
is, a release number consists of three numbers separated by dots in the form of
The version when you make incompatible API changes
The version when you add functionality in a backwards-compatible
manner
The version when you make backwards-compatible bug fixes
[ ]
Chapter 2
Additional labels for prerelease and build metadata are available as extensions to the
format.
One great way to name your tags is to match the existing milestones. From the
previous chapter, we already had a milestone so let's also name the new tag
. Start typing it and if the tag does not exist, you will see the Excellent! This tag
will be created from the target when you publish this release message.
the following screenshot:
If you choose a branch, a tag pointing to the latest commit in that branch will be
created. If you, instead, go to the Recent Commits tab, you can choose from a
number of recent commits to create a tag from.
For the sake of our example, let's choose the master branch and enter a release
title. Optionally, but recommended, you add a description of what this release is
about. I like to consider the description like writing a blog post of what changed
in this release.
[ ]
Using the Wiki and Managing Code Versioning
Preview button to see how it will be rendered:
[ ]
Chapter 2
If you think everything is in order, hit the Publish release
edit any release anytime, so do not worry if you miss something. The following
screenshot explains all the information about a release:
It's worth noting that the release date is the date of the latest commit. Although I just
released , you can see it dates 4 days ago.
If a release title is not provided, the tag name will be shown instead.
Likewise, if a description is not provided, the latest commit message
of the tag will be shown instead.
Editing a release
In order to edit a release, you must visit its own page, meaning clicking on the
version name at the releases page. The edit button will then appear and you will be
able to change what you like.
[ ]
Using the Wiki and Managing Code Versioning
Pushing a tag from the command line
Now, let's see how GitHub behaves when a tag already exists. I made a few changes
GitHub as follows:
If you now visit the tags page, you will see the new tag above the one we made
before. In the releases page, click on Draft a new release. We will choose an existing
tag, so at the Tag version . GitHub found out that the tag already
exists so it informed us that this is an existing tag:
Give it a title, a brief description, and then publish it. Since the tag refers to a
latest commit rather than the previous release, it now gets marked as Latest release.
A nice little decorative feature is that you can mark a release as a prerelease, meaning
to inform the users that it's not ready for production, but they can still download and
test it. Marking as prerelease is as easy as ticking the relevant option:
Let's then make a prerelease of the develop branch, which contains new commits that
do not exist in the master yet, and name it .
[ ]
Chapter 2
After publishing it, here is how the releases page looks like:
[ ]
Using the Wiki and Managing Code Versioning
If you tend to
required information and then save it as a draft.
This way, you can spend less time when the time comes to publish it.
A draft release is marked as an untagged reference, as you will see in the
releases page:
To continue editing it, click on the untagged link and hit Edit draft, as shown in the
following screenshot:
Since you are working on a draft, you don't have to worry about changing the tag
of the release or any other information for that matter. Drafts can only be viewed by
those who have write access to the repository, so it is not shown to the public until
they are published.
There are cases where you might want to provide precompiled binaries for a variety
of operating systems. For your Android application, it would be the
Windows, or ; for Debian, ; for RedHat, and so on.
[ ]
Chapter 2
When you create a release, there is a window at the very bottom that tells
you to attach any binaries. Here I uploaded a test
following screenshot:
GitHub released for you:
Tips and tricks
you familiarize yourself with Git, you'd be happy to know that you can edit a
project's wiki locally.
[ ]
Using the Wiki and Managing Code Versioning
Subscribing to new releases via atom feed
If you are used to subscribing to feeds to learn the news on your favorite blogs,
releases on GitHub.
Simply go to the releases page and append at the end of the URL.
For example, becomes
Editing the wiki locally
As mentioned in the wiki commit history section, every wiki is a separate git
repository. As such, you can clone it, make changes locally, and push back to GitHub.
It is powered by the ruby library that we will install and use to preview the
wiki locally.
Installing gollum
The library is packaged as a ruby gem, and the easiest and quickest way to
not the scope of this guide.
Cloning the wiki and see the preview in your browser
Back in our wiki page, you should have noticed the download link. Every wiki
repository has a remote URL encapsulated in green as shown in the following
screenshot; essentially, it is the URL of the main git repository with appended
to the URL:
[ 50 ]
Chapter 2
Use this URL and clone the wiki; then, run the command inside that
repository:
Although not stated, you can also clone the wiki using the git
protocol and not HTTP.
If you see an output similar to the following, then will successfully run and
you can preview the wiki in your browser at :
The interface should be familiar with the GitHub wiki. Let's make a few changes.
Now that you have a running instance of the wiki, you can make changes in the
browser much like in GitHub, or use an editor such as or and edit the
Since you already know how to edit the wiki in the browser, let's use an editor and
change the
Take a second to see the log with and compare it with the history of the
commits in GitHub (at
).
Now push the changes back to GitHub and visit the history page again. The new
commit should be there along with the new change.
If you want to write in a different markup language, other than
Markdown, see the readme at
for ways to install the gems needed.
[ 51 ]
Using the Wiki and Managing Code Versioning
Summary
In this chapter, you learned the importance of documentation and how GitHub
allows you to host a Markdown-powered wiki, along with every project. Creating,
deleting, editing, and reverting pages should by now be familiar terms.
second part of this chapter, you should already know what connects them and how
to create releases and distribute them to the public.
In the next chapter, you will see the management of organizations and teams.
Read on and learn how to harness the power of collaboration.
[ 52 ]
Managing Organizations and
Teams
It is important to know when to host a project under your namespace and when
under an organization. With the organization, you have the ability to create teams
and provide different access levels to people in the various repositories that are
hosted under it.
In this chapter, we will go through creating an organization, inviting people, and
will learn how to create teams and associate members of your organization to them
as well as with the repositories.
This chapter was written with the new improved organization
announced in June 2015. For more information, read the blog
post at
and the relevant page at
.
The difference between users and
Apart from your user account that should be used only by yourself, GitHub provides
the ability to create organizations managed by many users and, as we will see later,
create teams within the organization.
[ ]
Managing Organizations and Teams
need a handful of people to help with the maintenance.
This might not be the only reason why one should create an organization, though.
Leaving aside the practical reasons, an organization is usually created when there is
more than one person, each having equal rights to the projects that the organization
will host.
that have organizations under which dozens of projects are hosted.
permission levels
GitHub allows you to choose among three roles for a person in an organization:
owners, members, and billing managers. We will not deal with the latter; if you want
more information on this, refer to
.
Owners have full access to the organization and are in the highest level of the
permissions chain. As far as the organization is concerned, they can invite and
remove people, create and remove teams, create and remove repositories, as well as
manage the permission levels of all people and repositories. They can also edit the
organization settings.
Being a member is usually the default role when a new person gets in the
organization. The least a member can do is create a new team and add existing
team members and repositories to it.
The access level a member has over a repository can only be
set by an owner.
A member can also be promoted to "Team maintainer" for a particular team. With
this access level, they can add and remove team members. Consider it like an extra
hidden role on top of being a member. Anyone who creates a new team is granted
the "Team maintainer" role for that team.
[ ]
Chapter 3
Now, be careful not to mix organization permissions with repository permissions.
There are four kinds of permissions a repository can have: owner, admin, write,
and read.
Owner is the top universal permission level that is granted to organization owners.
With the Admin access, one has owner privileges but for the particular repository;
you can push to it, delete it, add or remove a team, change the team's permission
level, add outside collaborators, and so on. It is like creating a new repository under
your personal namespace. With the Write access, you can push to the repository;
Read grants you read permission which means clone and pull only.
For a comprehensive list of the various level permissions, check out GitHub's
documentation at
.
Now that we have discern the different access levels and permissions, let's create our
In order to
your avatar or visit directly:
[ 55 ]
Managing Organizations and Teams
testing purposes, you can give your personal e-mail, which you can change later if
you want. For open source projects, the creation of an organization is free, which is
the default plan. All these options are summarized in the following screenshot:
As you type the name, GitHub searches behind the scenes if it is already taken,
and if that is the case, a message appears saying that Username is already taken.
[ 56 ]
