Setup GitLab

Using GitLab for project management.

Creating your project

Once your team has been formed, you will need to create a project space in the University of Waterloo GitLab. You should create a single GitLab project for your team, and add the information detailed below. When done, you will need to submit your project details in Learn.

Step 1. Create using the new-project wizard

1. Open the GitLab home page.

2. Select + > New project/repository > Create Blank Project.

3. Fill in the form:

   • The project should be placed under the Username of one of your team members (e.g. j2avery in the example).
   • Visibility should remain Private.
   • Your project should have a descriptive name e.g., UberTweets or Social Calendar.

4. Select Create project to proceed.

Step 2. Set project security

It’s important that you set permissions on your project. This provides access to those who need it, while preventing others from accessing it!

The person who sets up the project should make the following changes:

1. Check project visibility.
   • Settings > General > Visibility Level
   • Ensure that it’s set to Private.

2. Add your teammates to the project with full access.

   • Manage > Members, Invite Members.
   • When they accept, change their role to Owner.

3. Add course staff with reduced permissions. Add the instructors and TAs to your project.

   • Manage > Members, Invite Members and use each person’s email address.
   • When they accept, set their role to Developer.

Teams will be assigned TAs in the middle of the second week of the term, before this deliverable is due. You can either wait for those details to be released, or just add all of the TAs and instructors to your project.

Step 3. Add project details

Optionally, you can also add a project icon, and other details.

• Settings > General, Project avatar.
• Settings > General, Project description.

FAQ

What should I name my project in GitLab?

Something meaningful is best, although you can always rename it later: Settings > General, and update the Project name field.

Does it matter which team member “owns” the project?

No. Just make sure that all team members are added propoerly. See Step 2 above.

How do issues relate to requirements?

The requirements that you discussed as part of your project proposal should be addressed by the features that you include. Each feature should be represented by one or more GitLab issues, with the details of how you will implement that feature.

Another way to think about the relationship is that issues are a representation of the tasks required to address the requirements.

How should I structure my issues so that they make sense?

In an ideal system, we could model this relationship as an umbrella of issues (work to be done) grouped under a parent issue (requirement). e.g.,

  %%{init: {'theme':'neutral'}}%%
flowchart TB
    Requirement --> Issue1
    Requirement --> Issue2
    Requirement --> Issue3

Unfortunately, GitLab doesn’t support issue hierarchies like this. It’s recommended that instead you create separate issues and link related issues together (using the Link field in the issue).

  %%{init: {'theme':'neutral'}}%%
flowchart LR
    Issue1 --> Issue2
    Issue2 --> Issue3

e.g. a requirement like “Create a user record” might break into multiple linked issues.

How do I create cool diagrams like that?

See the Documentation lecture. We write documentation in Markdown, and we use Mermaid to generate inline diagrams.

If you’re looking for examples, a lot of the sample projects have README files that contain diagrams.

What information should be in my issues?

An issue should contain:

• The complete description of the problem that you are addressing, or the feature that you are implementing. The issue is your main source of recorded documentation!
• Instructions on how to test it. Indication of what tests exist.
• Identification of any dependencies on other issues.

Some guidelines when deciding on the “size” of an issue:

• A task should represent approximately 1/2 a day’s work, on average. If a task is expected to take more than a day, look at splitting it into multiple sub-tasks, representing smaller units of work.
• Subtasks should remain logically related.

Think of an issue like a description of the task that needs to be completed, and any information that you might need to know to complete it. It’s a note to yourself and/or other team members.

Final Word