# Git Best Practices - Drupal ## Boston.gov-d8 Repo Branching City of Boston use Acquia to host our Drupal website. Acquia provide a number of different environments for COB to use. One of those environments is **production** the others are non-production - named: **stage**, **dev**, **uat**, **ci** & **dev2**. Detail on deployment is covered [elsewhere](/digital/guides/drupal-8/custom-development-and-configuration/continuous-deployment-process.md), but in summary we are able to "bind" certain branches of our GitHub repo ([CityofBoston/boston.gov-d8](https://github.com/CityOfBoston/boston.gov-d8)) to these Acquia environments, and when changes occur in those branches, a deployment is automatically triggered. Therefore, the way we branch-off, push-to and merge the "bound" branches is important. ### Normal Deployment Pipeline The `develop` branch is bound to the Acquia **dev** environment, and the `master` branch to the **stage** environment. *Changes cannot be made directly onto the `master`branch, and changes should not be made directly onto the `develop`branch - except when hotfixes are needed*. * Best Practice is to create a ***working branch*** off `develop` , then check out that `working branch` locally. * Updated code should be committed to the locally checked out copy of the `working branch` * Updating the local `working branch` will update the local containerized website for testing. * Periodically, the local `working branch` should be pushed to the remote `working branch` in GitHub*.* * Updating the `working branch` in GitHub will not trigger any deploys or update any website. * To start the deploy to the **dev** environment, a PR is created in GitHub to merge the `working branch` in GitHub into the `develop` branch in GitHub. * Merging will trigger a build and the website on the **dev** environment will be updated. * When ready to deploy to the **stage** environment, a PR is created in GitHub to merge the `develop` into the `master` branch in GitHub. * Merging will trigger a build and the website on the **stage** environment will be updated. * To deploy to the **production** environment, use the Acquia Cloud UI - see [continuous deployment](/digital/guides/drupal-8/custom-development-and-configuration/continuous-deployment-process.md#deploy-to-production) notes. ### On-Demand Pipeline We can bind a branch to the **dev2, ci** or **uat** environments so that we can share proposed or interim website changes with stakeholders or other individuals where a local containerized website is not appropriate. These environments can be considered on-demand, and the way to update them is similar but slightly to the normal deploy piepline, requiring an extra branch. Branches attached to environments other than **dev**, **stage** and **production** in Acquia are termed ***environment branches*** (see also [On-Demand Instances](/digital/guides/drupal-8/custom-development-and-configuration/on-demand-instances.md)). * Initially, an `environment branch` is created from the `develop`branch. * This `environment branch` is then bound to the desired Acquia environment (**dev2**, **ci** or **uat**). * Developers then create a `working branch` off the `environment branch` and check out that `working branch`locally. * Developers commit their work to the local copy of the `working branch` which can be pushed to the remote `working branch` in GitHub whenever desired. * Updating the local `working branch` will update the local containerized website for testing. * Updating the `working branch` in GitHub will not trigger any deploys or update any website. * When ready to update the website on the bound environment, using a PR, the GitHub copy of the `working branch` is merged to the `environment branch` in GitHub. * Merging will trigger a deploy to the bound Acquia environment (i.e. **dev2**, **uat** or **ci**) and update the website on that environment. * Stakeholders can be directed to the website on the Acquia environment. * Once the project or piece of work is complete, a PR to merge the GitHub`environment branch` to the `develop` branch is created. * Merging will trigger a deploy to **dev** and update the website. * To continue to deploy to **stage** and **production** environments, follow the notes in Normal Deploy Pipeline above. ### Branch Diagram Sometimes a picture is worth 1,000 words. ![Example Git Branch Usage](/files/-McMuQVPLuZCQWVUl6dL) In the above diagram, * Lines with an arrow indicate a merge to the branch in the direction of the arrow. * Lines with a dot connector indicate the creation (or updating) of a branch - and when the line is to a local branch it is a checkout to a local branch. * The `master` branch is the **production** branch and cannot be pushed/merged to directly. * The correct way to update `master` is to merge the `develop`branch into the `master` branch. * At all times the `master` branch should be a copy of the code on the production environment. (see [continuous deployment](/digital/guides/drupal-8/custom-development-and-configuration/continuous-deployment-process.md#deploy-to-staging-includes-automated-testing)) * Green arrows cause a deployment process: * Only if the branch being merged into is bound to an Acquia environment, and * This is controlled/executed by Travis, taking approx 3 mins (uses 30 Travis credits), and * The website hosted on the Acquia Environment is updated during the deploy. * Orange arrows cause a build, test and deployment process: * Only if the branch being merged into is bound to an Acquia environment, and * This is controlled/executed by Travis, taking approx 30 mins (uses 300 Travis credits), and * The website hosted on the Acquia Environment is updated during the deploy. * Travis is configured so that this is extended process usually only runs when committing to the `develop` branch - triggering a deploy to the Acquia Dev environment as the first step of the deployment pipeline. * Black arrows indicate a simple commit/merge process with no building or deploying: * Best practice reuquires that a `working branch` is not bound to Acquia Environments * Merging does not trigger Travis, there is no deploy and 0 Travis credits are used * **Note:** A GitHub `environment branch` can be bound to **one or more** Acquia Environments. When this is the case, deploys will occur simultaeously to all bound environments when the GitHub `environment branch` is updated. * Travis always controls deploys, but only one set of credits is used per `environment branch` merge regardless of how many Acquia environments it is bound to. ## Useful Links {% content-ref url="/pages/-LViXrxqhYu0KJ8tXPIF" %} [Continuous Deployment Process](/digital/guides/drupal-8/custom-development-and-configuration/continuous-deployment-process.md) {% endcontent-ref %} {% content-ref url="/pages/-LVeWClm9ssqeGgA\_8-Z" %} [Git / GitHub](/digital/standards-and-best-practices/git-and-github.md) {% endcontent-ref %} {% content-ref url="/pages/-LViWk66TnDcVFsuokSv" %} [On Demand Instances](/digital/guides/drupal-8/custom-development-and-configuration/on-demand-instances.md) {% endcontent-ref %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.boston.gov/digital/guides/drupal-8/custom-development-and-configuration/site-development-notes/git-best-practices-drupal.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.