These are our rules for Git branching - This is to prevent any unapproved work from being deployed to live environments, and to ensure all code is in the correct place.

---

## Set up

### JIRA

Always keep JIRA up to date with tasks that you're working on. These tasks should always be in the correct listing, based on their progress.

All JIRA boards should have the following lists (at least).

1. **Backlog** _Scheduled Work, Not started_
2. **In Progress**
3. **Approved** _Tested on staging environment, and approved for live_
4. **Done** _Pushed to production live environment_

If you're working on a JIRA board that doesn't have these 4 lists, please create them and use them as above.

Also, when adding a new Issue in JIRA, you can tag it with a label - please use the appropriate label based on what you're doing, e.g. `feature`, `hotfix` - This will give it more information so others are aware.

And don't forget to tag all commits to the JIRA issue, e.g. `feat/WR123: blog updates`.

The commit message should follow https://www.conventionalcommits.org/en/v1.0.0/.

---

### Jenkins

All of our Jenkins sites for staging sites, should now point to the `staging` branch for that repo.

So, as you work on a project, please make sure it's using `staging` and not `develop`. You don't need to bulk update everything, but when you work on it, please ensure it's following this new way.

---

### BitBucket Branches

**master**

> Production code

**develop**

> Code approved to go live, which will be pushed to a `release` => `master`

**staging**

> Code that's being tested on the staging environment, before it's approved for live deployment

**release**

> Created from `develop` with changes to go live

**feature**

> Created from `develop`, for new development jobs

**hotfix**

> Created from `master`, for bugfixes

> **Note: Don't finish your `feature`, until it's approved and ready to go live, as you may need to merge it into a hotfix**

---

## Your repo has a `staging` branch set up already

If you're working on a repo which follows these new rules already, these are the steps with new work.

1. Check JIRA to see what work is currently being done
2. Create a new feature branch, using `git flow feature start [name]`, and do your task
> _It's a good idea to prefix your branch name with the JIRA issue id, so that it's easy to see when you're working on it and switching between features, e.g. `feature/WR-102-blog-updates`_
3. When finished, push to your `feature`, run `git checkout staging`, and `git merge feature/[name]`. This will put your work in the `staging` branch, so it can be deployed to the staging website for testing/approval.

> _If you need to do more tweaks, then run `git checkout feature/[name]`, and make your changes, then run step 3 again._

4. Once this work is approved, run `git flow feature finish [name]`. This will move your work to `develop`, ready for a release.

> _If there are multiple features that have been approved to go live, then finish them all using the steps above. Once develop contains all your work that's going live, move to the next step._

5. Once all work is ready to go live, find out what your new tag should be ([conventions here](https://bitbucket.org/wrdev/developer-docs/src/master/dev-handbook/naming-conventions/git-versioning.md)), and create `git flow release start X.X.X.X`. When ready, run `git flow release finish X.X.X.X` and push to `develop` and `master`. Also, run `git flow --follow-tags` so that the tags are pushed to BitBucket.

---

## Your repo doesn't follow this convention yet

1. Run `git checkout master` , and `git pull`. Then create your `staging` branch, with `git checkout -b staging`, and `git push --set-upstream origin staging`. This will push this branch to BitBucket.
2. Check JIRA to see what work is currently being done.

2a. **If there is anything in `In Progress`, and it's in `develop`, then:**

2a-i. `git checkout master`, and then run `git checkout -b feature/[name]`. This will create a branch from `master`, but will not use the `git flow` conventions. This is to ensure that the code doesn't include any work that's not approved yet.

2a-ii. Do your work, and when ready, push to `staging` (_Following steps 3 & 4 from "Your repo has a `staging` branch set up already"_)

2b-iii. Once this work is approved, run `git checkout develop && git pull` && `git merge feature/[name]`. This will manually merge your work to `develop`, ready for a release. You can then delete this `feature` branch later, in BitBucket.

2b. **If there is nothing in `In Progress`, then:**

2b-i. Run `git flow feature start [name]`

2b-ii. Do your work, and when ready, push to `staging` (_Following steps 3 & 4 from "Your repo has a `staging` branch set up already"_)

2b-iii. Once this work is approved, run `git flow feature finish [name]`. This will move your work to `develop`, ready for a release.

3. Once all work is ready to go live, find out what your new tag should be ([conventions here](https://bitbucket.org/wrdev/developer-docs/src/master/dev-handbook/naming-conventions/git-versioning.md)), and create `git flow release start X.X.X.X`. When ready, run `git flow release finish X.X.X.X` and push to `develop` and `master`. Also, run `git flow --follow-tags` so that the tags are pushed to BitBucket.

---

## If Approved Features Need to Be Pushed Live and Develop Has Unapproved Work

To get round this, you can use a `hotfix` to push your `feature` to live.

1. Create a `hotfix` which will hold your new work to go live, e.g. `git flow hotfix start X.X.X.X`
2. Merge your `feature` into the `hotfix`, e.g. `git merge feature/[name]`
3. Finish your `hotfix`, `git flow hotfix finish X.X.X.X`, and push to `develop` and `master`. Also, run `git flow --follow-tags` so that the tags are pushed to BitBucket.
4. Then finish your feature, so it's not still open, `git flow feature finish [name]`