# An issue from start to merge, with commands

> A cheat sheet to keep open: every step from creating an issue to cleaning up after the merge, with the git commands, how to bring develop into your branch, and fixes for the usual accidents.

Source: https://laszlonemes.com/university/software-technology/issue-lifecycle · Author: László Nemes

Cheat sheet · Software Technology

A cheat sheet to keep open: every step from creating an issue to cleaning up after the merge, with the git commands, how to bring develop into your branch, and fixes for the usual accidents.

6 min read `Issue to branch` `Commit and push` `Merging develop in` `Merge request steps` `Cleaning up` `Common problems`

One page to keep open in the first weeks: an issue from creation to merge, with the commands. `ABC` is your project key, `origin` is the GitLab repository, every command runs in the repository root. The reasons behind each rule are on the [version control page](https://laszlonemes.com/university/software-technology/version-control); releases and hotfixes are on the [final product page](https://laszlonemes.com/university/software-technology/final-product).

After this session you can

- take an issue from the board to a merged MR without looking anything up
- keep a feature branch up to date with develop and resolve the conflicts yourself
- recover from the usual accidents: a commit on the wrong branch, a rejected push, a red pipeline

## The whole path

> **Fig. 1** · Four columns on the board, and what you do in each. The card moves when you start and when you open the MR; the merge closes it.
>
> *Diagram:* The four board states with what you do in each. Todo: create the issue from the Feature template with a title, a milestone and yourself, and move the card to Doing when you start. Doing: switch to develop, pull, create the feature branch, commit and push. Review: open the merge request into develop with Closes #12 and a reviewer, answer the review with new commits and resolve threads. If changes are requested the card goes back to Doing. Closed: after the merge, switch to develop, pull and delete the local branch.

## 0 · Once, at the start

Every member, every clone

```shell
git clone <repo-url>
cd <repo>
./setup-hooks.sh                         # cmd / PowerShell: .\setup-hooks.bat
git config user.name "Your Full Name"
git config user.email "<the e-mail address of your GitLab account>"
```

## 1 · Create the issue

- *Issues → New issue*, template **Feature** or **Bug**.
- Title in English, imperative: "Implement save/load". It becomes the branch name and the MR title.
- Fill the user story and the acceptance criteria, including an error case. Set the milestone and assign yourself.
- When you start: drag the card to *Doing*, or comment `/label ~"status::doing"`.

## 2 · Start the branch

Always from an up-to-date develop

```shell
git switch develop
git pull
git switch -c feature/ABC-12-implement-save-load

# or: issue page → Create merge request → Create branch, then
git fetch && git switch feature/ABC-12-implement-save-load
```

## 3 · Work and commit

Small commits, pushed daily

```shell
git status
git add -p                               # review each change before you stage it
git commit -m "add save file validation" # the hook turns it into "ABC-12: add save file validation"
git push -u origin feature/ABC-12-implement-save-load

./gradlew spotlessApply && ./gradlew test     # or: dotnet format && dotnet test
```

Run the formatter and the tests before you push – don't learn from the CI that it is red. Push at least once a day, even half-finished: the branch is your backup and the team's view of your progress.

## 4 · Bring in develop

If teammates merged into `develop` while you worked, bring their changes into your branch – conflicts are then resolved by you, on your branch, before the merge (Fig. 2).

> **Fig. 2** · Merging develop into your branch gives it both histories. The merge request then contains only your changes, and merges without conflict.
>
> *Diagram:* While you worked on feature/ABC-12, teammates merged two commits into develop. git fetch and git merge origin/develop create a merge commit on your branch that has both histories, so conflicts are resolved by you, on your branch, before the merge request is merged.

Merge develop into your branch

```shell
git fetch origin
git merge origin/develop
# conflict: edit the files, then
git add <files> && git commit
git push
```

Or rebase – only before review

```shell
git fetch origin
git rebase origin/develop                # only before anyone has reviewed the branch
git push --force-with-lease              # never plain --force, never on a shared branch
```

Good to know

**Merge or rebase?**

Merging is always safe. Rebasing gives a straighter history but rewrites your commits, so it needs a force push – fine on your own branch before review, never after a reviewer has started, never on a branch someone else works on.

## 5 · Open the merge request

- GitLab: *Merge requests → New merge request*, or the link git prints after the push. Source: your branch, target: `develop`.
- Title: the issue's title. Description: the template – what and why, how you tested it, `Closes #12`.
- Not ready yet? `Draft:` in front of the title; *Mark as ready* when it is.
- Name one teammate as reviewer and tell them on Teams. Move the card to Review.
- Answer the review with new commits on the same branch, reply to every thread, then resolve it.

## 6 · Merge and clean up

Conditions: an approval, a green pipeline, all threads resolved, no conflict. Then the author presses *Merge* (merge commit, *Delete source branch* ticked). `Closes #12` closes the issue and moves the card to Closed.

Back to develop

```shell
git switch develop
git pull
git branch -d feature/ABC-12-implement-save-load    # the remote branch was deleted by the merge
```

## Common problems

| Symptom | What to do |
| --- | --- |
| `remote: You are not allowed to push code to protected branches` | Good – the protection works. Create a branch and an MR. |
| The hook rejects the commit message | Read its output and fix the message. Not `--no-verify`. A missing key usually means you are on the wrong branch. |
| I committed on the wrong branch | Move the commit to a new branch, then reset the wrong one (below). Unsure? Ask before any reset --hard. |
| Conflict in the MR | Section 4 – the author resolves it, not the reviewer. |
| Red pipeline, "works for me" | Open the job log. Usually formatting, a file that isn't committed, or letter case in a file name. |
| A password or token got committed | Tell the team at once and replace the secret. Removing it from history is one person's job (git filter-repo); everyone re-clones afterwards. |

A commit on develop that belongs on a branch

```shell
# committed on develop by mistake (not pushed yet – the server would have refused anyway)
git switch -c feature/ABC-15-pause-menu  # the new branch keeps the commit
git switch develop
git reset --hard origin/develop          # develop goes back to the server's state
```

Common mistake

**reset --hard throws work away**

`git reset --hard` discards uncommitted changes for good. Run `git status` first, and only reset a branch whose commits are safe somewhere else. The [git post](https://laszlonemes.com/blog/git-and-github) has a figure on which undo command to use when.