> ## Documentation Index
> Fetch the complete documentation index at: https://sol.advantagelearn.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Git

# Git Solution Team Conventions

*A section to specify any agreed apon conventions our team follows in
respect of GIT*

## Branch Prefixes

*The Below prefixes are to be added to all branch names as a team standard
convention.*

| Prefix | Branch Type        | Related to                                                                            |
| ------ | ------------------ | ------------------------------------------------------------------------------------- |
| bug/   | Bug Resolve        | A bug in existing code, doesn't work as dev expected                                  |
| enh/   | Enhancement Branch | A tweak or improvement on existing functionality                                      |
| hot/   | Hotfix Branch      | A hotfix launched straight to production                                              |
| iss/   | Issue              | An issue experienced by a user, something missed or wrong with existing functionality |
| fea/   | Feature Branch     | Adding new functionality that didn't exist                                            |

## Gihub saved replies

Use GitHub saved replies to help quickly add commonly used templates for issues, pull requests etc.

[GitHub saved replies](https://docs.github.com/en/get-started/writing-on-github/working-with-saved-replies/using-saved-replies)

## Building a pull request (PR)

To build a PR you can checkout a branch using the branch prefix convention mentioned above.

`git checkout -b fea/feature-name`

There are a number of options to use as your base branch when checking out a new branch:

* In most cases you will use the `develop` branch as a base
* If you are doing work that requires the code from an existing PR branch, you checkout from that branch.
* If you are working on a hotfix you can branch off of the `main` branch

## Launching a pull request

When launching a pull request (PR):

1. Click the back arrow to add the Pull Request saved reply, this will add the PR checklist
2. Launch in **DRAFT** - Select the arrow next to the `Create pull request` button and select *Create draft pull request*

The reason we launch in draft is that a PR can only be published once the PR checklist has been completed.

## Completing a PR checklist

### Campus and Partner Applications

```
## Context

## PR Checklist

- [ ] PR branch based to default branch (or exising PR branch)
- [ ] Meaningful PR Name added (This will be in release notes)
- [ ] The changes have been added to the dev docs changelog
- [ ] Dev Docs have been added for new functionality introduced to capture nuances
- [ ] Relevant unit tests have been added
   - [ ]  No unit tests required
- [ ] Relevant Dusk tests have been added
   - [ ]  No Dusk tests required
- [ ] PHP Stan has been run `vendor/bin/phpstan analyse`
- [ ] Unit tests have been run and pass `php artisan test`
   - [ ]  No need for unit test to be run (very minor changes)
- [ ] Dusk tests have been run and pass `php artisan dusk`
   - [ ]  No need for dusk test to be run (very minor changes)
- [ ] Meaningful PR Description added (This will be in release notes)
- [ ] Link relevant issues
- [ ] Add reviewers to PR
- [ ] Add new env variables to .env file on Zoho Vault

## Changes

```

### Gamma

```
## Context

## PR Checklist

- [ ] PR branch based to default branch (or exising PR branch)
- [ ] CSS has been compiled
   - [ ] `gulp tailwindcss` has been run
   - [ ] `gulp` has been run
   - [ ] `functions.php` version has been bumped
- [ ] Styling changes made to the menu have also been made to the Neo Microsite
- [ ] Meaningful PR Name added (This will be in release notes)
- [ ] Meaningful PR Description added (This will be in release notes)
- [ ] Link relevant issues
- [ ] Add reviewers to PR

## Changes

```

`gulp` and `gulp tailwindcss` need to be run in order to minify any new CSS classes added to the branch. These minified classes are the ones used for styling on production, so without running these commands, the styling changes will not render correctly.

Similarly, the `functions.php` version needs to be bumped if:

* any new Tailwind classes have been added
* any changes have been made to the legacy themestyles `.scss` and `.js` files for them to render correctly on production.

## Publishing the PR

Once the checklist has been completed, you can publish the PR by clicking `Ready for review` at the bottom of the PR

## Releases

During the development process a number of Pull Requests and code changes are made to the `develop` branch. At certain intervals you will want to release these changes to the production application. This article outlines the flows to achieve this. Note that most apps will have an intermediary branch and environment in between develop and production called `staging`. The staging environment is used to test the release before it goes to production. In addition to this, some apps will break up the testing phase into two distinct phases: internal UAT (which is represented by the `qa` branch and `qa` environment), and external UAT (which is represented by the `staging` branch and `staging` environment). For those apps with a simplified testing phase, the `qa` branch and environment will not exist and references to it in these docs can be ignored.

## Production release flow

### 1. Launch to QA (internal UAT)

When code is ready for internal UAT (QA phase) you will merge `develop` into the `qa` branch. If an application is of a certain level, there will be a dedicated QA environment linked to the `qa` branch. This will allow an internal (non-dev) UAT process and to finalise that the release is stable for external UAT.

The time period that a release remains at this phase depends on requirements of the application and stakeholders.

> Applications that are not yet in production do not usually require staging environment to speed up development. The flow can go straight to checklist (3)

### 2. Changes to release during QA period (internal UAT)

Small changes and PR merges are common during a QA period, but usually only critical changes (or insignificant changes) that will stabilise the release during the QA period are considered.

All changes to QA can be done via direct commits or PR merges with the `qa` branch. These changes need to then be merged back into the `develop` branch.

### 3. Launch to staging (external UAT)

When code has passed internal UAT and is ready to be staged for external UAT release you will merge the `qa` branch into `staging` branch. If an application is of a certain level, there will be a dedicated staging environment linked to the `staging` branch. This will allow an external (non-dev) UAT process and to finalise that the release is stable for production.

The time period that a release remains at this phase also depends on requirements of the application and stakeholders. For the Salt Campus, the recommended staging period is 1 week. ie: the release is staged on the staging environment for a week prior to production release.

> Applications that are not yet in production do not usually require staging environment to speed up development. The flow can go straight to checklist (3)

### 4. Changes to release during staging period (external UAT)

Small changes and PR merges are common during a staging (external UAT) period, but usually only critical changes (or insignificant changes) that will stabilise the release during the staging period are considered.

All changes to staging can be done via direct commits or PR merges with the `staging` branch. These changes need to then be merged back into the `qa` and `develop` branches.

### 5. Create release PR and complete the release checklist

When a staged release has passed external UAT and is ready for production release, you need to create a release PR and the following checklist needs to be completed (in order).

```md theme={null}
## Release Checklist

-   [ ] Changelog items built into latest release in the app dev documentation
-   [ ] Release notes built into the app dev documentation (for sharing with team / stakeholders)
-   [ ] PHP Stan has been run `vendor/bin/phpstan analyse`
-   [ ] Unit tests have been run and pass `php artisan test`
-   [ ] Dusk tests pass
-   [ ] Staging environment log is free of errors (easiest checked with /log-viewer)
-   [ ] The version number is assigned vYYYY.MM.{Major #}.{Minor #} eg: `v2021.03.2.1`
-   [ ] Tag the release eg: `git tag v2021.03.2.1`
-   [ ] Change PR name to "rel/v2021.03.2.1"
-   [ ] Push the tag to origin eg: `git push origin v2021.03.2.1`
-   [ ] Build and publish release linking to tag - auto generate Github release notes
```

### 6. Process release

You can now process the release by merging the release PR into `main` / `master`. Once merged the automatic deployments should process and you can watch the Slack dev ops channels for notifications of successful release.

If the release was successful:

1. Double check the production applications are working as expected
2. Announce the release to stakeholders sharing release notes
3. Merge `main` / `master` back into `qa` an `develop` branches

## Hotfix release flow

* Branch off of `master` with hotfix branch `hotfix/*`
* Create release PR pointing to `master` with hotfix notes
* Stakeholders review hotfix
* Merge with `master` to launch release
* Merge `master` back into `staging` and `develop`