Skip to content
This repository has been archived by the owner on Sep 14, 2022. It is now read-only.

Community: Git Workflow

ebollens edited this page May 21, 2011 · 24 revisions

The UCLA Mobile Web Framework canonical code resides under the UCLA/MWF Git repository:

[email protected]: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.

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.

Institutional Fork

The following is an example of how UCLA fork operates within Git:

Institution Branch Model Flowchart

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. When this branch is merged to {institution}/master, it should also be merged to {institution}/develop, and when {institution}/develop is merged back into {institution}/master, it should also be merged to this branch.

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.

Institutional Fork: Forking the MWF Root Repository

Github Fork Approach (Recommended)

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 such as that Github forks are reflected in the Github MWF Network.

Manual Approach - Alternative

Alternatively, if you do not intend to use Github, or if you would prefer not to leverage Github's fork feature, then you can also 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 this process:

Institution Alternative Setup Flowchart

First, if not already done, 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 should refer to the institution's remote repository, and the "upstream" remote should refer to the MWF root remote repository.

git remote add origin [email protected]:{institution-repository}
git remote add upstream [email protected]:ucla/mwf.git

Pull the master 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

Institutional Fork: Set Up Long-Term Branches

Institution "master" Branch

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

Institution "maint" Branch

Define an {institution}/maint branch from the {institution}/master branch:

git checkout -b {institution}/maint {institution}/master
git push origin {institution}/maint

Institution "develop" Branch

Define an {institution}/develop branch from the {institution}/master branch:

git checkout -b {institution}/develop {institution}/master
git push origin {institution}/develop

Institutional Fork: Developing with Feature Branches

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} 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. 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".

MWF Root Repository

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:

  1. MWF Developer - Create a feature branch from the develop branch.
  2. MWF Developer - Develop within the feature branch until complete.
  3. MWF Developer - Create a "Merge Request" JIRA ticket.
  4. MWF Contributors - Code review of the feature branch by the MWF Contributors.
  5. MWF Coordinator - If approved, merge the feature branch into develop.

The feature shall remain in develop until such time as develop is merged to master by the MWF Coordinator.

MWF Root Repository: Developing with Feature Branches

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 "Move 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 s/he merge the current "develop" branch into the feature branch to resolve conflicts before the change can be accepted.

Clone this wiki locally