JK: This page is nearly there, just needs a gentle tidy

Code Management and Release Process

The code for the site, including all Drupal core, contrib and custom files (but excluding settings and uploaded assets) is stored in an Subversion (SVN) repository available at ​https://tech.transitionnetwork.org/svn/www/ and browser:www.

The code was previously in another repository, ​https://svn.webarch.net/transition/ and it was migrated to the current one, without the history, via ticket:92.

Principles

This process relies upon all developers understanding:

1. You never hack Drupal core
2. Developers work on their own machines and check into the DEV branch of the SVN repository (viewable here: browser:www/trunk) ONLY when their code TESTED functional.
3. The ​development server (DEV) mirrors the LIVE environment must be used to test this code before moving to LIVE.
4. There is a ​TEST server which can also be used as required, but is optional unless there is a lot of development work going on or many developers need to test their work in preparation for a release to LIVE.
5. The LIVE server ONLY EVER gets tagged releases put on it. Such releases must be tested (both on a local developer machine AND on DEV) prior to release. Hence, the LIVE server moves from one tagged release to the next.
6. Database backups must happen before each release to LIVE - this way each release on LIVE has an associated database backup. Go to 'Site building' -> 'Backup & migrate' (or use the command line NewLiveServer#mysql-backup script) to create the backup.
7. You can update the test and dev site's databases and files to match the live server using the DevelopmentServer#live2dev script.

Software & Getting Started

You obviously must have Subversion installed on your machine to work on this project. The basic SVN command line software available for most platforms in from ​http://subversion.apache.org/ - however, some very nice applications are also available that integrate into your operating system's graphical interface. Recommended FREE SVN applications with a nice GUI are:

• Windows: TortoiseSVN - ​http://tortoisesvn.net/downloads
• Linux: RabbitVCS - ​http://wiki.rabbitvcs.org/wiki/download
• Mac: Not sure, all seems commercial - anyone know better?

To get started, you need a copy of the code and ideally a web server (Apache), database (MySQL) and Drupal set up on your machine. We assume as a web developer you already have this, but Google and ​http://drupal.org/start are certainly your friends if not. Once you're set up, please run this command to get a copy of the current development (DEV) code.

cd /the/directory/you'll/be/working/in
svn checkout https://tech.transitionnetwork.org/svn/www/trunk

Once you have this, you will be able to edit files on your machine and then later commit them back to the repository - once TESTED of course! Note that the above checkout DOES NOT contain the Drupal settings.php files, nor any files uploaded to the server. It will contain the site's theme though: you will need to get or create these as needed for your setup and configuration. Please see

Release Process Detail

This process gets you from a basic checkout of the code, through committing and testing, to a proper release on the LIVE server. By now you should have a copy of the code checked out as per the section above.

The process is as follows:

1. Edit you code, test locally

As you modify the source code and theme files on your checked out working copy, the differences between your copy and the Trunk will grow. It's wise therefore to do smaller chunks of work and commit once these specific bits are completed. Clearly, if several developers are working on the same areas at once, you will have to coordinate your work and be more careful.

To update the Trunk (DEV) with the tested changes you've done so far:

cd /the/directory/you're/working/in
svn commit -m "A sensible description of what you've done"

Make sure you add a good description in case someone needs to roll back a commit to fix an issue. Then, repeat this step until you're ready to...

2. Test on the DEV server

This step is critical because the DEV server mirrors the setup on LIVE. Hence any issues or differences you didn't spot whilst working on your local machine can be ironed out here. It also allows you to get feedback on your work so far as required.

Note: To get files onto the server, you must have logged into the development server via SSH - for more on how to do this see wiki:DevelopmentServer#SSHaccess.

ssh dev.transitionnetwork.org.webarch.net
cd /web/dev.transitionnetwork.org.webarch.net/www
sudo svn up

The last command brings the DEV site up to the latest Trunk version. Go to ​http://dev.transitionnetwork.org.webarch.net/ and enjoy the fruits of your labour.

Depending on the changes, you should test properly and then solicit feedback and testing from managers/stakeholders. This is probably on DEV, but could be on TEST if needed.

3. 'Tag' (copy) the release

Once everyone is happy with the DEV site updates, you will nee/root/.my.cnfd to 'tags' (svn copy) the release so it's ready to be moved onto the LIVE server - or the TEST site if needed (more on that in a moment).

You need to SSH into the DEV server and go to the website root folder (as above). Then run these commands to tag the release:

sudo svn cp https://tech.transitionnetwork.org/svn/www/trunk https://tech.transitionnetwork.org/svn/www/release/2010-11-23 -m "Release version 2010-11-23"

All releases go in the browse:www/release folder on in the SVN repository with the date as the sub folder name. The above commands will make a copy of Trunk as it stands and then move it to a new folder ready for release to TEST or LIVE.

4. Release to LIVE (or TEST)

Please note the documentation for the LIVE server is here: wiki:NewLiveServer - and you should have decided whether or not it's necessary to do a run of testing on the TEST site before moving to LIVE... The process for both is the same, just on different machines.

4a. Prepare for release by...

1. SSH into LIVE (or TEST): ssh www.transitionnetwork.org (OR for TEST: ssh test.transitionnetwork.org.webarch.net)
2. Go to the site root folder cd /web/transitionnetwork.org/www (OR cd /web/test.transitionnetwork.org.webarch.net/www)

4b. Backup & put Drupal into maintenance mode: You are now ready to take the site down and get the new files onto the server, but first you need to make a backup and prepare in Drupal...

1. Log in as Transition Admin (user 1 - password available on request)
2. Go to 'Site configuration' -> 'Site maintenance' and put the site offline. Ideally update message so users can see when the site is likely to be back - allow 15 minutes.
3. Go to 'Site building' -> 'Backup & migrate' (or use the NewLiveServer#mysql-backup script) to make a manual backup of the database - which is saved on the server.

NOTE you will need to do points 2 and 3 above on the ​http://workspaces.transitionnetwork.org domain too!

4c. Deploy the new code: Back in the terminal where you are SSHed into the correct machine AND in the correct site root folder...

  sudo -i
  svn switch https://tech.transitionnetwork.org/svn/www/release/2010-11-19/ .

Using your release date, obviously. After a short while the server will complete the task and you can...

4d. Finish the job: Go back to Drupal in your browser and...

1. Go to the 'Database update' page at ​http://www.transitionnetwork.org/update.php (or test.transitionnetwork.org/update.php) and complete the process.
2. Go to the homepage, initiatives directory, blogs etc and check the site is looking and behaving like it should. If it isn't you will need to fix the issue. If you can't you will need to roll back - see the next section.
3. Repeat the update process on the Workspaces subdomain.
4. Go to 'Site configuration' -> 'Site maintenance' and put the back main site online. And the Workspaces sub-site.
5. Let everyone who needs to know the site is back and updated. Then have a beer.

5. Rolling back a release

If it goes badly, don't panic. You have all the old code in SVN and a snapshot of the database just prior to updating it. To roll back, run the following commands on the server you're logged into:

1. (Assuming you can still use Drupal) Take the site back offline and go to 'Site building' -> 'Backup & migrate' -> 'Restore' (if the NewLiveServer#mysql-backup script has been used then the restore will have to be done via the command line).
2. Restore the database backup just prior to the and make a manual backup of the database - saved on the server.

If you can't use Drupal you will need to use the command line to restore the database backup you made. Essentially this consists of going to the /web/transitionnetwork.org/www/sites/default/files/backup_migrate/manual folder and getting the database snapshot file you made (or /var/backups/mysql/ if the NewLiveServer#mysql-backup script was used, note this script backups up all the databases not just the Drupal one), then running a command like:

mysql live < TransitionNetwork-TransitionAdmin-2010-07-05T11-08.mysql

If you do this as root you don't need to specify the host, user or password as they will be read from /root/.my.cnf).

Once the database is back, WITHOUT doing anything more in Drupal, switch the files back:

  sudo -i
  svn switch https://tech.transitionnetwork.org/svn/www/release/[the previous release]/ .

That's the files back so clear the caches and test the site.