Community: Git Workflow
The UCLA Mobile Web Framework canonical code resides under the UCLA/MWF Git repository:
git@github.com:ucla/mwf.git
Although one may download the MWF directly, the recommended workflow entails creating a fork of the central repository. This simplifies the development process for those using the framework, as it makes it easy to merge framework updates into an institution-specific codebase. The process for doing this is described below.
Note: When merging, it is recommended to always specify the "--no-ff" option to avoid losing commit history. Ex: git merge --no-ff {branch_name}.
To clear up one bit of confusion, though the Git workflow characterizes the branching process as "forking", these forks are intended to be campus-specific and do not entitle redistribution of the UCLA Mobile Web Framework in part or in whole, as the framework is subject to the restrictions of its source-available license. The MWF project retains this creative control over its source code for two primary reasons: (1) it is in the best interest of all participants to centralize development efforts on a single master copy of the framework rather than to see the framework splinter into distribution forks, and (2) this ensures consistency of framework deployments that make it easy for all branches using the framework to merge new features and upgrades from the master.
The following is an example of how UCLA fork operates within Git:
The premise of this model relies on several branches within the institutional fork:
- master - A vanilla (mirror) copy of the master in the MWF root repository that occasionally pulls from the MWF root repository (remote) to update the institution's codebase.
- {institution}/master - The production copy of the framework with institution-specific changes that is tagged for production releases. This version pulls from {institution}/maint and {institution}/develop occasionally to bring in maintenance and feature changes, and it also pulls from master to bring in MWF root changes.
- {institution}/develop - A developed feature branch into which feature branches are merged once they are completed and reviewed. This branch is occasionally merged back into {institution}/master.
- {institution}/feature/{name} - A feature branch that stems from {institution}/develop that encapsulates the development of a feature. Once approved, this is pulled into {institution}/develop. The developer may also make a request through the process described below in MWF Root Repository - Feature Development to get this change merged back into the MWF root repository.
Some institutions have also found another branch useful (not depicted in the flowchart):
- {institution}/maint - A hot-fix maintenance branch for the institution's framework team to make quick fixes. These fixes are then merged back into {institution}/master. This should be a non-persistent branch that is created from {institution}/master, modified, and then immediately merged back into {institution}/master and deleted. See Institutional Fork: Maintenance & Hotfixes section below for details.
NOTE: For institutions intending to contribute code back to the MWF project from the institution repository, it is highly recommended that an approach that uses feature branches be used.
The recommended way to set up an institution fork is by accessing the Github MWF Root Repository and clicking the Fork button in the upper left hand corner. This will cause Github to create a Fork in your personal or organization account.
More information on this process is available in Github's Fork a Repository documentation. This has some major positives over the alternative approach listed below including the fact that Github forks are reflected in the Github MWF Network.
Alternatively, if you do not intend to use Github, or if you would prefer not to leverage Github's fork feature, then you can set up the institution fork manually. A fork set up in this way is not reflected in the Github MWF Network
This flowchart roughly depicts the process:
First, if not already done so, configure Git to use your GitHub account information.
git config --global user.name '{github-name}'
git config --global user.email {github-email}
Create a local directory and initialize it as a Git repository.
mkdir {repository}
cd {repository}
git init
Create a pair of remotes that point to remote repositories: The "origin" remote refers to the institution's remote repository, and the "upstream" remote refers to the MWF root remote repository.
git remote add origin git@github.com:{institution-repository}
git remote add upstream git@github.com:ucla/mwf.git
Pull the master branch from the MWF root remote repository:
git pull upstream master
Push the MWF root repository's master into the institution's remote master:
git push origin master
Create local branch {institution}/master from the MWF root repository master branch, and push {institution}/master to the {institution}/master branch of the institution's remote repository.
git checkout -b {institution}/master master
git push origin {institution}/master
Define an {institution}/develop branch from the {institution}/master branch:
git checkout -b {institution}/develop {institution}/master
git push origin {institution}/develop
New features should all be developed within feature branches. This simplifies the process of merging features back into both the institution's develop branch and potentially back into the MWF repository as well.
Create a new local feature branch:
git checkout -b {institution}/feature/{name} {institution}/develop
git push origin {institution}/feature/{name}
Commit changes to the local branch feature branch:
git checkout {institution}/feature/{name}
git add {files}
git commit -m "{50-character-description}
{detailed-description}"
Push commits from the local feature branch to the remote repository:
git push
When a feature is completed, the institution's central mobile team should then review it and merge it back into {institution}/develop. After merging, the local develop branch should also be pushed to the remote repository. Note: When merging, the --no-ff option should always be specified to avoid losing commit data.
git checkout {institution}/develop
git merge --no-ff {institution}/feature/{name}
The {institution}/develop branch is used as a staging area for {institution}/master. If the code is also to be contributed back to the MWF repository, then the developer should also set up a "Move Request" JIRA ticket in the Mobile Web Framework issue tracker. In the event of such a contribution back to the MWF root repository, please see the section "MWF Root Repository - Feature Development".
When an institution needs to make quick minor updates (perhaps for stopgap or hotfix solutions on production servers) that do not warrant a full release, they can make use of a non-persistent {institution}/maint branch to apply updates to the {institution}/master branch. The procedure to do this is as follows:
Define an {institution}/maint branch from the {institution}/master branch:
git checkout -b {institution}/maint {institution}/master
git push origin {institution}/maint
Apply and commit necessary fixes to {institution}/maint branch, then push it to the remote.
git commit
...
git push origin {institution}/maint
Merge {institution}/maint into {institution}/master and push it to the remote.
git checkout {institution}/master
git merge --no-ff {institution}/maint
Finally, delete the {institution}/maint branch on the remote so that it does not remain persistent, and remove it from your local repository as well.
git push origin :{institution}/maint
git branch -d {institution}/maint
The central project development cycle itself leverages several branches of UCLA/MWF:
- master - The canonical version that all institutions should fork with changes merged from the develop and maint branches
- develop - The development branch that all feature branches are merged into by the UCLA MWF team.
- feature/{name} - A feature branch created from the develop branch where a feature is
All central project development itself follows a Git branching workflow:
- MWF Developer - Create a feature branch from the develop branch.
- MWF Developer - Develop within the feature branch until complete.
- MWF Developer - Create a "Merge Request" JIRA ticket.
- MWF Contributors - Code review of the feature branch by the MWF Contributors.
- MWF Coordinator - If approved, merge the feature branch into develop.
The feature shall remain in develop until develop is subsequently merged to master by the MWF Coordinator.
Create a new local feature branch:
git checkout -b feature/{name} develop
Initial push of the local feature branch to the remote repository:
git push origin feature/{name}
Commit changes to the local branch feature branch:
git checkout feature/{name}
git add {files}
git commit -m "{50-character-description}
{detailed-description}"
Push commits from the local feature branch to the remote repository:
git push
Once the feature is in a state ready to deploy, the MWF Developer should then create a "Merge Request" JIRA ticket in the Mobile Web Framework issue tracker. The following code review by MWF Contributors will then lead to either acceptance of the feature, at which point the MWF Coordinator merges the code from the feature branch back into the develop branch, or rejection of the feature, at which point the MWF Developer should then return to the feature branch to continue work. If merge conflicts occur, the MWF Coordinator may send it back to the MWF Developer to request that he/she merge the current develop branch into the feature branch to resolve conflicts before the change can be accepted.