- DEVELOPER GUIDE
- Development workflows
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.
- IRC channel: #ows-fga on irc.freenode.net
- Meeting calendar: google calendar, ical/gcal feed
- Mailing List: email@example.com
- join the PRIMARY discussion list at: https://lists.riseup.net/www/info/ows-fga || archives
- join the UX list at: https://lists.riseup.net/www/info/ows-fga-ux || archives
- join the data list, primarily serving curators of the Occupy Directory: https://lists.riseup.net/www/info/ows-fga-data || archives
- join the Occupation Directory list: https://lists.riseup.net/www/info/owsdirectory || archives
- Our Communication Practices explain how we use communication tools to keep the project together.
Our code exists simultaneously in 2 environments github (public) and Pantheon (restricted access). The live server is running off the Pantheon MASTER branch.
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.
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.
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:
You can also add something more catch-all like:
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.
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();
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 = firstname.lastname@example.org:97d52c78-0b43-45a2-9d65-20c8a431706b [remote "github"] fetch = +refs/heads/*:refs/remotes/github/* url = email@example.com:fga/fga-directory.git [remote "all"] url = firstname.lastname@example.org:fga/fga-directory.git url = email@example.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
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.
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
This is where you should be theming, and toying around, and rolling new features.
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).
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.
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.