Contribution workflow - Issues and merge requests

Why bother?¶

Agreeing on how to handle day-to-day operations increases productivity and reduces the potential for miscommunication
- Reduces onboarding time for new project members
- Reduces setup time for new projects
Workflows that deal with similar types of projects should be similar
- There is no one-workflow-to-rule-them-all
- Adapt established workflows to team- or project-specific needs

An Example Contribution Workflow¶

A contribution workflow regulates how changes to the files of the project get planned, agreed upon, executed and verified.

In this course, a workflow will be presented that is especially suited for GitLab (or GitHub) and can be applied for many types of projects. The following is an overview, the details will be subject of the following episodes.

Open an issue
- Detail the intended changes
- Notify potential stakeholders
Discuss the details
- Clarify open questions.
- When working face-to-face this can be kept to a minimum. Write down the decisions that were made in meetings or attach a protocol.
Open a new merge request
- This signals that someone is working on it
- A merge request automatically generates a Git branch to be used.
Make iterative changes
- Add commits to the branch
- When satisfied request a review of the changes made
- Adapt according to the reviews
Once the reviewers approved the changes, merge the working branch into the main branch of the project (or any other target branch for that matter)

As a rule of thumb: - Discuss the details of the problem and solution approaches in the issue - Discuss the actual presented solution in the merge request

Issues¶

Issues are a conversation-style medium for outlining, planning and managing tasks and processes
They form the entry point for common use-cases like
- Bug reports
- Feature requests
- Discussions and decision making
Issues can be assigned to a person who is responsible for handling the issue
A real world example: https://gitlab.com/gitlab-org/gitlab/-/issues

Live Coding: Create an Issue¶

(Issues => New issue, fill in details, Create issue)
- Title: My first issue
- Assignee: Yourself
Start a discussion in the comment section
See the result in the issue overview page (Issues)

How to Write Good Issues¶

Writing good issues is a valuable soft-skill for teamwork. A good issue draws attention, has high information density and provides all details to get started with solving it.

If available, use the appropriate issue template
Be brief and precise
Use the markdown formatting
Provide all required details

When and How to Close Issues¶

Issues can lead to merge requests
- When this merge request gets closed or merged, the associated issue automatically will be closed
Issues can also be closed directly if no merge request is needed
- When closing an issue without a merge request, give a reason and/or summary as last comment
It is recommended to regularly (e.g. monthly) schedule an issue-housekeeping
- Check if issues are still relevant
- Add updates to these issues if available
- Close issues that are no longer valid
  - If the issue has been solved, add a link to the commit or merge request that solved it

Labels¶

Labels are a tool for categorization
They can be attached to issues or merge requests
Available either for a single project (project label) or all projects within a group (group label)
Labels have a name, an optional description and a color
- Colors can be chosen from a list
- Note: The intuitive meaning of colors can vary between cultures
Labels can be prioritized and manually given a priority
Do agree on a label policy and document it in the contribution guide

Example Use Cases for Labels¶

Workflow-oriented
- ToDo, Planning, In Progress, Review
Type-oriented
- Bug, Fix, Feature, Maintenance, Chore, Documentation, Discussion
Priority-oriented
- Critical, High, Medium, Low
Affected subsystems
Expected difficulty
Common other labels
- Help Wanted, Good First Issue

Live Coding: Create Labels¶

Create the following labels (Project information => Labels, New label):
- Documentation (color blue)
- Discussion (color blue)
Switch to your issue (Issues, Select the issue)
- Assign the label Discussion to your issue
- Close the issue (Close issue)
See the result in the issue overview page (Issues)

Other Notable Features¶

Merge Requests¶

What are Merge Requests¶

Merge Requests (short MR) visualize the development process on a git branch, including:
- Commits
- Conversations
- Assignees
- Relations to issues and other MRs
They form the basis for reviews
Note: This feature has different names on different platforms:
- In GitLab: Merge Requests
- In GitHub: Pull Requests

Creating Merge Requests¶

MRs can be created based on
- Existing issues (will create a new branch with an automatically generated name)
- Branches pushed via git
After creation, a MRs’ title, description and merge options can be set anytime
Like issues, MRs can have labels and assignees

Making Changes¶

To add changes to the MR
- Push commits to the MR branch via git
- Use the WebIDE

Interaction¶

The interaction principles (commenting, adding files, referencing) are similar to the ones already seen for issues. Particularly, when performing reviews, sticking to a good review practice makes the difference between reviews being a dreaded nuisance or a valuable team experience. We refer to Philpp Hauer’s Blog Post on Code Reviews for further information.

Live Demonstration: Contribute a README¶

The README is the front page of your project. You can learn more about important files here: https://codebase.helmholtz.cloud/hifis/software/education/hifis-workshops/foundations-of-research-software-publication/workshop-materials/-/blob/master/episodes/03_add-essential-documentation.md

SETUP:
- One instructor is the Contributor and the other one is the Owner.
- The Owner adds the Contributor to his/her GitLab project in the role Developer.
- The Contributor starts by cloning the Git repository of the Owner.
Create an issue (Issues => New issue, fill in details, Create issue) (role Contributor):
- Title: Add a README
- Description: We want to provide an initial README file which serves as an introductory page for the project.
- Assignee: Yourself
- Label: Documentation
Create a merge request from the issue (Create merge request, leave details as they are, Create merge request) (role Contributor)
- Clone the other’s repository for further development (role Contributor)
CHANGE: Change the branch from the local Git repository (role Contributor)
- Pull the remote repository (git pull)
- Switch to the branch (git switch 2-add-a-readme)
- Add the README.md file with the following content:
```
# Planets

This repository contains notes about potential planets for migration.
```
- Commit message: Add an initial README
- Push to the remote branch (git push)
- Show the changes of the merge request
- Add the Contributor section via a second commit and show the results.
Go back to the merge request (Click on the link !1) and watch the changes (role Contributor)
- There are changes to review now
- Mark the merge request as ready (Mark as ready)
- Assign the Owner as reviewer
Review and merge the changes: (role Owner)
- Review the changes and show some of the interaction options (comments, change proposals)
- Merge the merge request (Merge)
Check the result in GitLab: (role Owner)
- See the changes in merge request list (Merge requests)
- See the changes in the issue list (Issues)
- See the changes in the Git history (Repository => Graph)
Update the local Git repository: (role Contributor)
- Switch to the Git shell
- Switch to the main branch: git switch main
  
  Older versions of Git use git checkout main
- Pull the changes from the remote repository: git pull
- Remove the local branch via: git branch -d 2-add-a-readme
- To get rid of the no longer needed remote branches, do a special fetch: git fetch --prune (will remove all origin/… branches that no longer exist)