History

« Previous - Version 23/36 (diff) - Next » - Current version
Andrew Mallis, 07/13/2012 04:26 am

DEVELOPER GUIDE

Welcome! This page is your one-stop shop for getting started developing for the FGA project. If you're new to redmine, maybe start here.

We're assuming that you are experienced with Drupal. And have a local development environment set up. Check out this resource if you need help with that.

Contact Information

Code

Our code exists simultaneously in 2 environments github (public) and Pantheon (restricted access). The live server is running off the Pantheon MASTER branch.

Github

FGA has an organization on github and the following projects are currently manifested there:

However, the production workflow for FGA is happening in Pantheon. Github is currently used only to manifest our codebase publicly. Drupal files and the database are also key to instantiating a local development copy, and these can be most easily made accessible via Pantheon.

Pantheon

Pantheon is a hosted development and deployment platform. For addition support, please seee their help desk

Registration

FGA developers should register for Pantheon if they haven't already. Registration is free and can be done here

Once registered, send an email to info [at] assembli.es requesting to be added to the TEAM, and specify which project(s) you're joining as well as the email address associated with your Pantheon account.

Pantheon workflows

local development set-up

The Pantheon workflow promotes local development. There is lots of documentation out there describing how to set up a local installation. We'll defer this question to the www to limit the scope of this wiki (external links welcome).

Once you've got the codebase checked out, create your own site inside sites, with a dedicated settings.php file. The git stack does track sites/default/settings.php, but decouples the database connect array. This allows us to add and track our own variable overrides and configurations. To keep your multisite container from being tracked by git you can simply add an entry to your home folder's git ignore policies (located in ~/.gitignore) like so:

directory.occupy.local

You can also add something more catch-all like:

sites/*.local
or
sites/*/settings*.php

One advantage of running your own multisite instance is that you can create a modules folder in there, and test locally before moving things to sites/all/modules. everything inside your local site will be ignored by git.

DRUSH ALIASES

Once you're on a project, its drush aliases will be packaged for you on Pantheon, and be accessible from your account page:

If you haven't used drush aliases before, you'll be impressed when you see them in action.

The file you download will be called pantheon.aliases.drushrc.php
I have mine in ~/.drush/aliases/pantheon.aliases.drushrc.php alongside my aliases.drushrc.php file.
Test your aliases with

$ drush sa

From your local environment, you can synchronize the development database like so:
$ drush -y sql-sync @live.fga-directory.gotpantheon.com @directory.occupy.local
(replace directory.occupy.local with whatever you call your site containing your local settings.php)

Synchronize the files from the production instance to local:
$ drush -y rsync @live.fga-directory.gotpantheon.com:%files/ @directory.occupy.local:%files $ drush cc all

You can also simplify your aliases by specifying shorter alias labels, like so (values X'ed out for security) and dropping these in aliases.drushrc.php:

$aliases['directory.dev'] = array(
  'root' => '.',
  'uri' => 'dev.fga-directory.gotpantheon.com',
  'remote-host' => 'appserver.dev.XXXXX.drush.in',
  'remote-user' => 'dev.XXXXX',
  'ssh-options' => '-p XXXX -o "AddressFamily inet"',
 );

then, you can run a more memorable command, like:

$ drush -y rsync @directory.live:%files/ @directory.local:%files

If you prefer, can put your aliases in a site-specific directory.aliases.drushrc.php file, in which case, $aliases['directory.dev'] = array(); will simply become $aliases['dev'] = array();

More info on Drush aliases on Drupal.org

note that drush sql-sync currently does not work from Pantheon to your local environment. This is a known issue and is being discussed here

Managing the Pantheon–github relationship

Here's the contents of my local .git/config to manage the integration between the Directory in Pantheon and github:

[core]
    repositoryformatversion = 0
    filemode = true
    bare = false
    logallrefupdates = true
    ignorecase = true
[remote "origin"]
    fetch = +refs/heads/*:refs/remotes/origin/*
    url = git@code.getpantheon.com:97d52c78-0b43-45a2-9d65-20c8a431706b
[remote "github"]
        fetch = +refs/heads/*:refs/remotes/github/*
        url = git@github.com:fga/fga-directory.git
[remote "all"]
        url = git@github.com:fga/fga-directory.git
    url = git@code.getpantheon.com:97d52c78-0b43-45a2-9d65-20c8a431706b
[branch "master"]
    remote = origin
    merge = refs/heads/master
git pull --rebase

comes from Pantheon. Note that we generally prefer the use of git pull --rebase, as it avoids ugly merge commits. This works approach works unless we start doing complicated feature branching (this article explains a more robust technique, if you're interested - we're not using it).
Or, pull from github with the remote:

git pull --rebase github

You can

git push all

to hit both github and Pantheon at the same time. Unless you have a reason not to, run the above command for every upstream push!

I don't recommend pulling from all, because it won't merge well, as git is too busy shuffling the deck to merge that process properly.
Pull one, then the other and both github and Pantheon will merge nicely.

It's important to note that only code in Pantheon can be pushed through the dev-test-live workflow. For now, that's where everyone is rolling, but if we want to develop more publicly, it might be desirable to work in github de facto. Our hope is that an auto-integration tool between github and pantheon will emerge so that we can update one from the other, so that you can just push to github, and that will push to pantheon dev. We'd need to

Features sometimes seriously reshuffles stuff, so merging isn't always obvious and you want to know asap if features have been modified and github pull requests can work well for this.

Development workflows

Drupal development for our projects employs a Features (Drupal.org documentation) workflow on git (Pro Git online documentation). We're exposing code to the public on github, but active development is happening on Pantheon

LOCAL
This is where you should be theming, and toying around, and rolling new features.

DEV
http://dev.fga-directory.gotpantheon.com
When you push from your LOCAL git repo to Pantheon, the DEV instance will automatically get updated. Awesome.

Features when re-rolled can sometimes arbitrarily re-order code blocks, or change indentation. Multiple local developers affecting the same Feature can sometimes loose much time resolving complicated 3-way merges. In these instances, work can often most easily be performed on the DEV environment, then Features re-rolled from there via the UI and committed from LOCAL. Git commits can't happen on the server itself (Pantheon does not provide shell access).

TEST
http://dev.fga-directory.gotpantheon.com
Content is pulled downstream, and code is pushed upstream from DEV.
Here, content curators, and site admins can try out new features, or test out operations they are fearful might compromise the live site's integrity.
Any content or configuration entered here is to be considered volatile, and subject to being wiped during the next synchronization.

LIVE
http://directory.occupy.net
New content should be entered here.

Pushing code live should ONLY happen during scrums, so that adequate testing can occur, and emergency measures can be taken if issues arise.
Unfortunately, Pantheon does not offer granular permissions and anyone can push to live PLEASE DO NOT push to LIVE independently

Generally speaking, hotfixes should not happen on LIVE, since overridden Features are subject to being reverted.

Branching and Tagging model

Pantheon creates a tag for each synchronization between environments. Topic or feature branches are a good idea for development, but Pantheon can only run off the Master branch in all 3 environments.

pantheon-team-ex.png (64.9 kB) Andrew Mallis, 04/08/2012 02:50 pm

dl-pantheon-aliases.png (45 kB) Andrew Mallis, 04/08/2012 03:46 pm

pantheon-download.png (24.9 kB) Andrew Mallis, 09/06/2012 03:07 pm