# Using GitLab's Issues, Epics, and Merge Requests to get things done

@startuml
class Issue {
    promoteToEpic(): Epic
    createMergeRequest(): MergeRequest
}

class Epic {
    createChildEpic(): Epic
    createChildIssue(): Issue
}

class MergeRequest {
    featureBranch
}

Issue "*" - "*" MergeRequest
Epic "1 parent" -- "* child" Epic
Epic "1 parent" -- "* child" Issue

@enduml

## Issues

Before doing any work, first create an issue for the work to be done. This provides a place to plan, design, and discuss work to be done, allowing developers to construct a common understanding of the work to be done.

> Info: In GitLab, all issues must belong to a single project.

## Epics

Ideally, each issue should represent a single, atomic, independent, logical unit of change. If it isn't, it probably needs to be broken down into smaller issues. To do this, first promote the issue into an epic. Then use the epic to break down the problem into sub-issues and sub-epics. From an epic you can create child epics and issues. The new epics and issues are autmatically linked to their parent epic.

> Tip: **Always start by creating issues, and promote them to epics as needed.** Why? Issues can be promoted into epics, but epics cannot be demoted into issues.

> Info: In GitLab, all epics must belong to a single group.

## Merge requests

When its time to work on an issue which requires modifying a repository (e.g., writing code, updating documentation, etc.), from the issue create a merge request. This will automatically create a feature branch and a merge request based on the issue title. It will also cross-link the issue to the merge request such that when the merge request is merged, the issue will be closed.

Now you are ready to commit changes to the feature branch assoicated with the merge request.

When you think the merge-request is ready to be reviewed and merged, mark the merge-request as ready, and let the reviewer(s) know it needs to be reviewed.

> Info: In GitLab, all merge requests must belong to a single project.