Framework Development and Release Workflows

In this document, we'll cover:

• Key Takeaways
• Development Workflow
  • Setting up your Development Environment
    • Clone Responsive Framework
    • Clone Responsive Foundation
  • Link the Foundation and Framework Repositories
  • Development Considerations
• Release Workflow

---

This guide details the development and release workflows put in place to help manage changes to the framework over time.

Key Takeaways

• The http://id-responsi.cms-devl.bu.edu sandbox should be used for all new feature development and bug fixes.
• The http://id-presents.cms-devl.bu.edu sandbox should always use the current stable release of Responsive Framework, consistent with production.
• Always run git pull in your local Framework and Foundation repositories when beginning development.
• All development for both the Framework and Foundation files should occur in the develop branch, or in specialized topic branches that get merged into develop.
• New releases are created by merging changes from the develop branch into the main branch and generating a new version tag (e.g. 1.2.3).
• Releases follow semantic versioning conventions.

Development Workflow

Determine which version of Responsive Foundation

Different versions of Foundation are used in different versions of the Framework, child themes, and Responsive Child Stater. When starting development, determine which version of Foundation you need to update. See: https://github.com/bu-ist/responsive-foundation/wiki/Responsive-Foundation-Versions

All new development for Foundation and Framework occur in the develop branches, or in specialized topic branches that are merged into develop. These changes should get pushed via SFTP to the Responsi development sandbox:

• URL: http://id-responsi.cms-devl.bu.edu
• Remote Server: ist-wp-app-devl01.bu.edu
• Remote Path: /var/www/sandboxes/id-responsi/current/wp-content/themes/responsive-framework-2x

All other environments, including http://id-presents.cms-devl.bu.edu, should use the latest stable tagged release of Responsive Framework. This should always be kept in sync with production so that child theme developers are working off of the latest Framework release.

Setting up your Development Environment

Core framework development follows a similar workflow to child themes, but adds a bit of special sauce to support modifying Foundation source files in parallel.

1. Clone both the Framework ( 2x or 3x ) and Foundation repositories.
2. Determine the branch to checkout:

• Checkout the develop branch in each repository if working on the latest version.
• If working on an update to an older release of Foundation such as 3x, or 4x the develop branch is no longer appropriate as it is farther ahead. Instead you'll need to create a branch from a previous release, such as from a tag. This will require using git on the command line as Tower does not appear to have a way of creating that.

3. Determine the version of node that must be used. Use nvm (Node Version Manager) to switch node to the correct version in both repos. The version of node used differs for different versions of Responsive Framework and Responsive Foundation. It is critical that both repositories are using the same version of node for npm link to function as the symlinks created are stored globally for each version when using nvm.
4. Link the Foundation and Framework repositories together using npm link. See: NPM Link Guide
5. Run the grunt command to automatically re-generate static assets as you work.

Note that these steps assume that you have installed Node, and Grunt and Bower as detailed in the Getting Started guide.

Clone Responsive Framework

First clone the Framework repository using Tower or by using the following commands in your Terminal:

$ cd path/to/your/themes
$ git clone [email protected]:bu-ist/responsive-framework.git
$ cd responsive-framework
$ git checkout develop

If you receive an error message complaining about public keys while cloning check to make sure you've set up SSH keys correctly for your Github account.

Next, install development dependencies using Node Package Manager:

$ npm install

In some older child themes, you may also need to run bower install here to install the Responsive Foundation package. This step is skipped for core framework development, as we need to work in a clone of the Foundation repository in order to commit changes to it.

Clone Responsive Foundation

In order to make changes to the Foundation files, you first need a local clone of the repository. You can do this by cloning the repo using Tower, or by using the following commands:

$ cd path/to/your/themes
$ git clone [email protected]:bu-ist/responsive-foundation.git
$ cd responsive-foundation
$ git checkout develop

To make changes to the Foundation files immediately visible while working on the Framework, you need to link the repositories together. NPM has a handy shortcut for this.

Link the Foundation and Framework Repositories

NPM can be used to establish a link between the Framework and Foundation repositories during development.

Starting in the Foundation repository:

$ cd path/to/responsive-foundation
$ npm link

This will let NPM know that you intend to create a link to the Foundation repository. To actually create the link, change in to the Responsive Framework theme directory:

$ cd path/to/responsive-framework
$ npm link responsive-foundation

This will create a symlink to the Foundation repository in the node_modules directory where NPM would normally install it.

You can now run the grunt command on your responsive-framework folder and begin development.

Why do we run grunt on responsive-framework if we're making changes in responsive-foundation? By itself, all Foundation is is just a set of CSS. Just like CSS without HTML is sort of useless, Foundation without Framework isn't very helpful, because without Framework there is no WordPress theme to see your CSS changes on. That's why no matter whether you're making changes to Framework or Foundation, you always have to run grunt on Framework, and you'll always need to commit and push both Foundation and Framework if you make a change to Foundation.

Development Considerations

For child theme development, the Foundation files are referenced by tagged release in package.json and pulled in via NPM for development. This ensures that everyone that clones a child theme is working off the same version of Foundation.

In some older themes, this is achieved with Bower instead, and follows the same setup, except using bower.json.

For Framework development we establish that relationship manually using two separate repositories. Always run git pull (or pull using Tower) in both your Framework and Foundation working copies to ensure they are up-to-date before beginning development.

If you don't your compiled output may differ from others. While this should be caught during the release process, it's always best to make sure your local repositories are up-to-date before starting development.

The other important thing to remember is that with Git commits are local; no one can see your commits until you have explicitly published them to the remote repository (Github) using git push.

Updates to Foundation and Framework files should happen in the following order:

1. Add and commit source file changes in Foundation. Run git push, or push in Tower, to publish these changes remotely.
2. Add and commit theme changes in Framework. Run git push, or push in Tower, to publish these changes remotely.

The key point being -- you should never commit Framework changes that include assets generated with a version of Foundation that is not published remotely.

Release Workflow

Every change to the Responsive Framework and Foundation must be tagged prior to production release. NOTE: ALL changes should be in develop.

• Ensure that the develop branches for both the Foundation and Framework repositories are up to date by running git pull.
• Increment the version number in package.json and run grunt version to propagate the new version to project files (functions.php, and style.scss).
• Recompile all static assets using grunt build.
• Document all changes introduced in the new version in CHANGELOG.md.
• Commit changes
• Create a new tag as you push as Version bump to [version].
• Merge changes from develop to main. (In Tower, be on main branch and drag develop onto main.)

In a case of a hotfix (merging changes from main into develop), aka when you need to push a fix into main without taking any of the changes currently in develop, and then merging the fix back into develop:

• Ensure that the main branches for both the Foundation and Framework repositories are up to date by running git pull.
• Increment the version number in package.json and run grunt version to propagate the new version to project files (functions.php, and style.scss).
• Recompile all static assets using grunt build.
• Document all changes introduced in the new version in CHANGELOG.md.
• Create a new tag as you commit as Version bump to [version].
• Merge updates from main back to develop.
• Push changes.

See "Creating a new release" for more information.