GitLab Setup

GitLab is a source code hosting platform similar to GitHub or BitBucket. The University of Waterloo maintains a hosted instance of GitLab, and you can login at https://git.uwaterloo.ca using your UW credentials ¹.

We need some way to track project information, in a way that is transparent and makes information available to everyone on the team.

There are many ways of accomplishing this. Some organizations track project artifacts on paper, with written SRS documents, requirements and estimates on spreadsheets, written test plans and so on². However, this is very inefficient, requiring changes to be carefully coordinated across different documents and tracking systems. More recently, it has become common to use online project tracking. We’ll use GitLab to track all of our project artifacts.

Capabilities

GitLab offers the following functionality high-level functionality:

Feature	Description
Repository	Version control for source code, or other files.
Issues	Mechanism to track project tasks or issues. They can capture details, be assigned a due date, passed between people and have an associated status that changes as the project progresses (e.g. Open, Closed).
Wiki	Create online documents using Markdown. This is very useful for longer-documents (e.g. design documents).
CI/CD	Continuous Integration and Deployment. We can setup rules that will automatically test or deploy our source code when it’s committed (or other conditions are met). This includes powerful analytics and reporting capabilities (that are beyond what we will cover in this course).
Snippets	Share snippets of source code outside of the project.

Project Tracking

Here’s some suggestions on how we can use GitLab at each phase of the SDLC:

Phase	SDLC Activities	GitLab Feature
Planning	We need to document project goals and objectives; log and assign requirements (which we can track as issues).	Wiki, Issues
Requirements	Definition and elaboration of requirements that are identified during the Requirements stage. Update issues as required.	Wiki, Issues
Analysis & Design	Track design decisions that are made and documented during the Analysis and Design phase. Document these decisions and make information available.	Wiki
Development	Log and document issues³ that are discovered during the Development phase. Manage feature branches and store source code.	Issues
Testing	Log and document issues that are discovered during the Testing phase. Manage unit tests. Handle continuous integration.	Issues
Evaluation	Log issues that are found. Log change requests (CR)⁴, based on customer feedback.	Issues
*	Manage source code, tests and all related materials. Ensure that we are using consistent versions of everything.	Repository

Project Structure

Setup

To start using GitLab for this course, you should do the following:

Create a new blank project in GitLab with a meaningful name and description.
When it opens, select Members from the left-hand menu. Invite each member of your team with the appropriate role: typically, Developer or Maintainer for full access.
Check to ensure that each member can login on their own machine using their own credentials.
Optional. Under Settings - General, add a project description. Create and upload an avatar!

Organization

Most project information can be tracked in the Issues menu (left-hand side when the project is open).

Each major deliverable should have a milestone attached to it. For this project, this means that each sprint should be a separate milestone.

Under Issues-Milestones, create suitable milestones (aka deadlines). Make sure to assign dates to these!
Under Issues-Labels, create keywords that will help you organize your issues.
Under Issues-List, create all of the issues that you wish to work towards. At the beginning of your project, none of your issues should be assigned to a person; they should be listed as “No milestone”, since you haven’t scheduled them yet.

Common Tasks

Writing Documents

GitLab projects have a Wiki attached to them, which you can use to create hyperlinked documents, with formatting, images and so on. It’s an ideal place to store any documentation that you might create, from your Project Plan, to an SRS, to Architecture digrams. A Wiki also has the advantage of staying up to date with your other project details. e.g. you can create a Project Plan that links to Issues in your GitLab project.

GitLab uses Markdown as its native format (specifically GitHub-Flavored Markdown), a common human-readable data format⁵.

Tracking Issues

GitLab has the ability to attach and track issues to a project, as shown below.

An issue is meant to represent some unit of work that can be appled to the project. Historically, they often referred to “bugs” or software defects. However, for planning purposes, there is little difference between a feature, a change request and a bug - they all represent work that needs to prioritized, assigned to someone and scheduled.

As suggested above, your defaults for a new issue should be Assignee: Unassigned, Milestone: No milestone. When you schedule it into a Sprint, then you change the Milestone to reflect that sprint and the assignee to the team member responsible for it.

Updating Issues

Issues should be considered living documents, that reflect the current state of your work.

Issues should be assigned as part of the sprint kickoff
when you do something significant, you should add a comment to the issue! this helps you recall, and helps your team mates if they need to help out.
when you complete it, mark it completed.

You can create and host your own projects here as long as you remain a student. Make sure to backup your projects before you graduate! ↩︎
You will find that some disciplines or industries require more scrutiny than others. If you work in Healthcare for instance, you will need to carefully track every requirement and change that is made to a system. ↩︎
An issue is considered a “Defect” or a feature that is not working as it was initially defined. ↩︎
A change request (CR) is a request to modify a feature from it’s original requirements and design. While a defect may be viewed as a “mistake” made by the team, a CR is viewed as a late-change to the requirements. This distinction often affects the priority of the issue or CR. ↩︎
Markdown is much nicer to read than many other semi-readable formats like HTML, and there’s a lot of tools to convert it into stylized HTML, PDF, EPUB and so on. As a matter of fact, this website is written in Markdown and converted to HTML. You should use it for README files and other bundled documentation. ↩︎