-
Notifications
You must be signed in to change notification settings - Fork 0
Git & Deployment
Branching | Deployment Summary | Troubleshooting | Workflow Diagram | Commands | WP Engine Git Push
Important things to remember:
-
Make sure you are always pulling from master.
-
Thorough testing after big changes. Deploy in a more piecemeal manner
-
Make sure you run
npm run productionafter your development session is over (this command compiles & minifies the files for production) -
Only one person to push to the production.
After changes have been pushed to the Staging Site send a link to Kat for review.
-
When you take on a task:
-
Go to the applicable Github repo and choose the issue to work on
-
Assign this issue to yourself
-
Create your Git Branch
a. If this is a critical hotfix that needs to get released immediately:
$ git checkout -b hotfix-[hotfix-name] stable // creates a local branch $ git push origin hotfix-[hotfix-name] // makes the branch remotely availableb. If this is a new feature/improvement:
$ git checkout -b feature-[feature-name] master // creates a local branch $ git push origin feature-[feature-name] // makes the branch remotely availablec. If this is a non-critical bugfix:
$ git checkout -b bug-[bug-name] master // creates a local branch $ git push origin bug-[bug-name] // makes the branch remotely available -
As work gets to stable stopping points or completion, push it to github:
$ git push origin your-branch-name // pushes branch to github -
When your code is ready to be reviewed:
-
Go to your branch on github.com and create a new pull request to be merged into master (or stable if a hotfix).
-
Drop any implementation notes into the github.com Issue and link the pull request to the github.com Issue in the Issue right sidebar.
-
-
After your code is reviewed:
-
It will either be merged or comments will be left so you can finish up the issue. Go ahead and repeat from #1 while you wait for the review.
-
For deployment flow, see the Deployment Summary.
-
Quick Legend
| Instance | Branch | Description, Instructions, Notes |
| Stable | stable | Accepts merges from Working and Hotfixes |
| Working | master | Accepts merges from Features/Issues and Hotfixes |
| Features/Issues | topic-* | Always branch off HEAD of Working |
| Hotfix | hotfix-* | Always branch off Stable |
The main repository will always hold two evergreen branches:
masterstable
The main branch should be considered origin/master and will be the main branch where the source code of HEADalways reflects a state with the latest delivered development changes for the next release. As a developer, you will be branching and merging from master.
Consider origin/stable to always represent the latest code deployed to production. During day to day development, the stable branch will not be interacted with.
When the source code in the master branch is stable and has been deployed, all of the changes will be merged into stable and tagged with a release number. How this is done in detail will be discussed later.
Supporting branches are used to aid parallel development between team members, ease tracking of features, and to assist in quickly fixing live production problems. Unlike the main branches, these branches always have a limited life time, since they will be removed eventually.
The different types of branches we may use are:
- Feature branches
- Bug branches
- Hotfix branches
Each of these branches have a specific purpose and are bound to strict rules as to which branches may be their originating branch and which branches must be their merge targets. Each branch and its usage is explained below.
Feature branches are used when developing a new feature or enhancement which has the potential of a development lifespan longer than a single deployment. When starting development, the deployment in which this feature will be released may not be known. No matter when the feature branch will be finished, it will always be merged back into the master branch.
During the lifespan of the feature development, the lead should watch the master branch (network tool or branch tool in GitHub) to see if there have been commits since the feature was branched. Any and all changes to master should be merged into the feature before merging back to master; this can be done at various times during the project or at the end, but time to handle merge conflicts should be accounted for.
<tbd number> represents the project to which Project Management will be tracked.
- Must branch from:
master - Must merge back into:
master - Branch naming convention:
feature-<tbd number>
If the branch does not exist yet (check with the Lead), create the branch locally and then push to GitHub. A feature branch should always be 'publicly' available. That is, development should never exist in just one developer's local branch.
$ git checkout -b feature-id master // creates a local branch for the new feature
$ git push origin feature-id // makes the new feature remotely available
Periodically, changes made to master (if any) should be merged back into your feature branch.
$ git merge master // merges changes from master into feature branch
When development on the feature is complete, the lead (or engineer in charge) should merge changes into master and then make sure the remote branch is deleted.
$ git checkout master // change to the master branch
$ git merge --no-ff feature-id // makes sure to create a commit object during merge
$ git push origin master // push merge changes
$ git push origin :feature-id // deletes the remote branch
Bug branches differ from feature branches only semantically. Bug branches will be created when there is a bug on the live site that should be fixed and merged into the next deployment. For that reason, a bug branch typically will not last longer than one deployment cycle. Additionally, bug branches are used to explicitly track the difference between bug development and feature development. No matter when the bug branch will be finished, it will always be merged back into master.
Although likelihood will be less, during the lifespan of the bug development, the lead should watch the master branch (network tool or branch tool in GitHub) to see if there have been commits since the bug was branched. Any and all changes to master should be merged into the bug before merging back to master; this can be done at various times during the project or at the end, but time to handle merge conflicts should be accounted for.
<tbd number> represents the github.com Issue # to which Project Management will be tracked.
- Must branch from:
master - Must merge back into:
master - Branch naming convention:
bug-<tbd number>
If the branch does not exist yet (check with the Lead), create the branch locally and then push to GitHub. A bug branch should always be 'publicly' available. That is, development should never exist in just one developer's local branch.
$ git checkout -b bug-id master // creates a local branch for the new bug
$ git push origin bug-id // makes the new bug remotely available
Periodically, changes made to master (if any) should be merged back into your bug branch.
$ git merge master // merges changes from master into bug branch
When development on the bug is complete, [the Lead] should merge changes into master and then make sure the remote branch is deleted.
$ git checkout master // change to the master branch
$ git merge --no-ff bug-id // makes sure to create a commit object during merge
$ git push origin master // push merge changes
$ git push origin :bug-id // deletes the remote branch
A hotfix branch comes from the need to act immediately upon an undesired state of a live production version. Additionally, because of the urgency, a hotfix is not required to be be pushed during a scheduled deployment. Due to these requirements, a hotfix branch is always branched from a tagged stable branch. This is done for two reasons:
- Development on the
masterbranch can continue while the hotfix is being addressed. - A tagged
stablebranch still represents what is in production. At the point in time where a hotfix is needed, there could have been multiple commits tomasterwhich would then no longer represent production.
<tbd number> represents the Basecamp project to which Project Management will be tracked.
- Must branch from: tagged
stable - Must merge back into:
masterandstable - Branch naming convention:
hotfix-<tbd number>
If the branch does not exist yet (check with the Lead), create the branch locally and then push to GitHub. A hotfix branch should always be 'publicly' available. That is, development should never exist in just one developer's local branch.
$ git checkout -b hotfix-id stable // creates a local branch for the new hotfix
$ git push origin hotfix-id // makes the new hotfix remotely available
When development on the hotfix is complete, [the Lead] should merge changes into stable and then update the tag.
$ git checkout stable // change to the stable branch
$ git merge --no-ff hotfix-id // forces creation of commit object during merge
$ git tag -a <tag> // tags the fix
$ git push origin stable --tags // push tag changes
Merge changes into master so not to lose the hotfix and then delete the remote hotfix branch.
$ git checkout master // change to the master branch
$ git merge --no-ff hotfix-id // forces creation of commit object during merge
$ git push origin master // push merge changes
$ git push origin :hotfix-id // deletes the remote branch
There are three sites that make up our deployment flow:
- Dev: https://cmedev.wpengine.com
- Staging: https://cmestaging.wpengine.com
- Production: https://mediaengagement.org
If it is not a hotfix, the flow for a normal deployment is:
-
FIRST make sure you run
npm run productionbefore deploying. -
mastergets deployed to https://cmedev.wpengine.com for testing.$ git push dev master // deploy to dev -
If all checks out well,
mastergets merged intostable:$ git checkout stable // change to the stable branch $ git merge master // merge without the commit object so we can just tag the spot instead of having a separate commit. Kind of like an active, rolling release branchIn terminal VIM enter
:wqto write the current file and exit.$ git tag -a <tag> -m "<add a message if you want or just include the tag>" // tags the fix $ git push origin stable --tags // push tag changes -
Push stable to staging for testing:
$ git push staging stable // push stable to staging -
If all checks out well, push stable to production for the launch:
$ git push production stable // push stable to production -
Login to WP Engine and clear all caches (view screenshot). You can also clear the cache & reset file permissions per-site through the WordPress WP Engine plugin (view screenshot).
git merge --abort // aborts the merge
If the merge issue is in the .css or .js files, rebuild production assets:
npm run production
. . . if it works, commit the merge.
If the WP Engine codebase differs from the GitHub repo (like a WordPress or plugin update), an error will show when you try to push. So you’ll need to pull from that source and resolve conflicts, if any.
If you get a failed to push some refs error like this:
! [rejected] stable -> stable (fetch first)
error: failed to push some refs to '[email protected]:production/cmengage.git'
!!! AT YOUR OWN RISK!! run a force push:
git push -f production stable
View the Workflow Diagram image
-
The
.nvmrc(/wp-content/themes/engage/.nvmrc) file contains the Node version required (node version16.13.2) for the project. In order to enable the version switch on each dev session you need to first run:nvm use. . . this command will switch your project node version to the version in the
.nvmrcfile. For windows users, checkout nvm for windows. Then you can run the commands below: -
To open a browser window with live reloading run:
npm run watch -
When you are done, to compile your code & minify for the production server be sure to run:
npm run production
See where your local files are at
git status
Move to master branch
git checkout master
Pull from master
git pull origin master
Merge feature branch with master branch
git merge feature-slider-mobile-fix
Push to dev master
git push dev master
Check your remote setup
git remote -v
Add dev remote to your setup
git remote add dev [email protected]:production/cmedev.git
Pull changes from master
git pull
Force push to dev master
git push -f dev master
Add all files to commit
git add .
Set remote repository URL
git remote add staging [email protected]:production/cmestaging.git
git remote add production [email protected]:production/cmengage.git
Confirm WP Engine connectivity
ssh [email protected] info
-
Navigate to the ‘cmengage’ instance on WPEngine
-
On the left sidebar, select ‘Git push’
-
Type in developer name with the format cmengage-(yourname)
-
Get your ssh key by going to terminal (or for Windows systems, Git Bash) and inputting:
ssh-keygen -t ed25519 -C "[email protected]" -f ~/.ssh/wpegitkey** Be sure to replace [email protected] with your own email address
-
Leave the passphrase blank by hitting enter or return again, without typing anything.
-
Press enter or return again to confirm the password entry.
-
Doing this will generate your public/private key pair
-
Print and copy the text of your new public key file, called wpegitkey.pub:
cat ~/.ssh/wpegitkey.pub -
Paste the entire key into the SSH public key field on WPEngine (Sites/cmengage/Git push)
-
Click ‘Add Developer’
the changes take a few minutes to register
-
Open terminal
-
To ensure that the repositories are added run:
ssh -v [email protected] info -
cd into your local website directory (~/app/public/wp-content/themes/engage)
-
To add production run:
git remote add production [email protected]:production/cmengage.git -
To add staging run:
git remote add staging [email protected]:staging/cmengage.git -
To check the remote repositories were added run:
git remote -v -
You should see an output like this if all remote repos have been added:
dev [email protected]:production/cmedev.git (fetch)
dev [email protected]:production/cmedev.git (push)
origin https://github.com/engagingnewsproject/enp-platform.git (fetch)
origin https://github.com/engagingnewsproject/enp-platform.git (push)
production [email protected]:production/cmengage.git (fetch)
production [email protected]:production/cmengage.git (push)
staging [email protected]:production/cmestaging.git (fetch)
staging [email protected]:production/cmestaging.git (push)