GitLab workflow
Documenting tasks can get really messy if not organized properly. Therefore all tasks (open to-dos, bugs to look at, or simply clean-up work) shall be documented and processed in a standardized way. This wiki section covers the usual workflow of handeling a task:
If you are not yet familiar with git, have a look here: How To Use Git?
in GitLab you can find Issues in the sidebar. As a subsection you will also find "Boards": a Kanban board we are going to use this semester, more on this later.
To create an issue, go to the Issues page and find the blue "New Issue" button on the top right. When writing the Issue, you should supply a (descriptive!) title and a comprehensive description. For this it's recommended to use the templates created for this repo, you will find them in the "Choose a template" dropdown list. The premade templates cover 3 issue types
- Bug: for when you will report bugs (e.g. "clicking on this button doesnt work", etc.)
- Feature: for when you suggest to add a new feature (e.g. "hey guys, we should add an export feature", etc.)
- Chore: for when cleanup is needed somewhere (e.g. variable names, moving files etc. - any internal task, that will not be noticeable to the user)
You will find further instructions on how to write the description once you select one of them. Please make sure the descriptions are comprehensible. So go into detail and maybe even add screenshots where they could be useful.
After you wrote the description:
- Add an assignee (the person who will take care of this issue) if you happen to know who it is going to be already.
- Add any (lowercase) label (e.g. "frontend", "bug", ...) that applies. (uppercase labels are used to move the cards in the kanban board, they describe in what state the issue is, e.g. "Doing")
For bigger goals/features like implementing a new algorithm we use Milestones. These can be used to group issues to give them a common description and track the progress on that specific goal.
After creating the ticket you can click on it in the list view. It will show you the description and any activity regarding the issue. It will also show a blue button "Create merge request" or "Create branch" (the name changes according to options). Click on the dropdown arrow on the right of the button, select "Create branch" and then click the blue button "Create branch" (see screenshot). This will create a branch for you in the repo. You can now check it out locally and start adding your code:
git fetch origin
git checkout <id-your-branch-name>
tip: use the tab key to autocomplete the branch name
At this point you can go to the kanban board, assign yourself to the issue and drag it into the "Doing" column.
Once you think you're done, you should move the issue to the "Review" column in the kanban board, and open a merge request. To create merge request click on "Merge requests" in the sidebar and create a new one. As Source branch select the branch with your changes on it (e.g. id-your-branch-name) and as Target select main. Done! You can add a person as reviewer if you want them to review your changes.
Once your changes have been reviewed and all problems have been resolved, one of two things (depending on the size of the issue) will happen:
(1) the merge request is merged and the issue closed, and you are ready to move on,
or for big issues
(2) documentation is needed: In this case, the Issue will be moved to the "Documenting" column and the developer is/are asked to write an entry about the newly introduced feature in the GitLab wiki. After this the issue is resolved just like in (1).
If someone else merges changes into main that touch the same parts of the code as your branch, you might run into merge conflicts when trying to merge. GitLab will catch this, block the merge and alert you. There are a few ways to resolve conflicts: if you're working alone on the branch and you're comfortable with using git rebase, you can do that. Otherwise, use git merge. If you run into any issues, feel free to ask for help!
→ Also: if main has new commits that don’t conflict with your branch, GitLab will just do a fast-forward merge when you merge through the UI — nothing extra needed on your end.