Promoting webdesigns through to production - tooltwist/documentation GitHub Wiki

In the future, ToolTwist will provide the ability to define custom approval processes, with approvals and versioning of navpoints, pagedata and snippets, to extend the current widget handling.

For the current version (v8.0) specific items can be selectively promoted through multiple stages into production. The most common scenario is as follows, but other configurations are possible:

    Designer --> master branch --> staging branch --> production branch

We use a different git branch for each stage, and create a launchpad for each of those branches. The Designer typically displays and updates on the master branch. Whenever it checks in the web design, a launchpad set up for Continuous Integration (CI) pulls from the master branch and updates the CI server. Standard Jenkins / Git configuration can be used to deploy cyclically (e.g. every 15 minutes) or triggered using a git or github hook. Alternatively, builds can be manually triggered from the Controller.

To promote the webdesign through to a staging environment, it is merged onto a different branch (normally named staging). Similarly, files can be promoted through to production but merging onto another branch (normally named - you guess it - production).

Non-standard flows can also be used - there can be any number of stages, and they may fork. In most cases the standard flow is best, as it avoids confusion.

A git repository needs to be created for the web design project, specifically for the purpose of promoting files through the various stages to production. Note that this is a totally separate repository and should not be the Designer's web design repository, or a repository used by the Controller, etc.

This new repository needs to be created by hand, and should contain all the branches you will use before the promote procedure is used.

$ cd $HOME
$ mkdir gitPromote
$ cd gitPromote
$ git clone [email protected]:PCMall/macmall-design.git
Initialized empty Git repository in /home/widgetti/macmall-design/.git/
remote: Counting objects: 133387, done.
remote: Compressing objects: 100% (36315/36315), done.
remote: Total 133387 (delta 43512), reused 133265 (delta 43390)
Receiving objects: 100% (133387/133387), 430.36 MiB | 8.38 MiB/s, done.
Resolving deltas: 100% (43512/43512), done.

Next you need to create the new branches, and save them to the remote repository.

$ git fetch --all --prune
$ git branch staging
$ git branch production
$ git push --all

If the repository already contained the branches, you need to check that they exist in the local version of the repository. Use the following commands to check. If the branches are missing, use Google and a git reference to solve the problem.

$ git checkout staging 
$ git checkout production 

One final important step is required. By default, Git will have trouble pushing commits to the current branch if there are conflicts on another branch. The following tells Git to only commit the current branch by default:

$ git config push.default current

Moving files through these stages is done using the menu options from the Repository menu in the Designer. By default only the first stage is provided, to Sync to the CI environment. Additional steps are defined in the web design project's properties.xml file.

<properties>
	...

	<gitPromoteDirectory>/home/widgetti/gitPromote/macmall-design</gitPromoteDirectory>
	<gitPromote>
		<label>Promote from test to Staging</label>
		<sourceBranch>master</sourceBranch>
		<destinationBranch>staging</destinationBranch>
		<backgroundColor>yellow</backgroundColor>
		<requiredRole>ttdesigner-approve</requiredRole>
	</gitPromote>
	<gitPromote>
		<label>Promote from staging to Production</label>
		<sourceBranch>staging</sourceBranch>
		<destinationBranch>production</destinationBranch>
		<backgroundColor>red</backgroundColor>
		<requiredRole>ttdesigner-approve</requiredRole>
	</gitPromote>
</properties>

The gitPromoteDirectory element defines a directory that will contain a git repository used for this promoting.

Restart the server, and the new options should be available under the repository menu.

The Sync with Repository... menu option is displayed if the user has the ability to approve widgets (role ttdesigner-approve).

By default all promote menu options get displayed under the Repository menu in the Designer, until such time as a requiredRole is defined in properties.xml (see the example above).

To create a custom role use the ToolTwist administration screens:

1. Use Maintain Roles to define a new role (e.g. ttdesigner-promote-to-production).

2. Add this role to properties.xml.

3. Use Role to User Mapping to control who sees the menu option.

This approach merges one branch onto another branch, and can be used to propagate changes through any number of stages and branches. Beware however that it merges - it does not replace a branch with the contents of the previous branch.

Consequently is very important that changes are not made directly to any of the branches, except the branch used by the Designer. If a branch gets corrupted or polluted you may need to delete the branch and recreate it from the preceding stage's branch.

--