Practical SVN for PHP Developers Matthew Weier O'Phinney Project Lead Zend Framework Lorna Jane Mitchell Software Engineer Ibuildings

What is Version Control?

What did you change from the previous revision? What changes have others recorded since your last local update? Change Management

What did you change from the previous revision?

What changes have others recorded since your last local update?

Types of Version Control

Each checkout is a fully functional repository Anybody may accept patches from anyone else Anybody may send patches to anyone else Ideal for projects with parallel feature developement Distributed

Each checkout is a fully functional repository

Anybody may accept patches from anyone else

Anybody may send patches to anyone else

Ideal for projects with parallel feature developement

One canonical repository All changes are submitted to the repository All changes are retrieved from the repository Ideal when: a canonical version is required, access to the repository should be controlled Non-Distributed

One canonical repository

All changes are submitted to the repository

All changes are retrieved from the repository

Ideal when:

a canonical version is required,

access to the repository should be controlled

What is Subversion?

Non-Distributed Version Control System Successor to CVS Stores and versions: source code documentation anything, really Subversion is...

Non-Distributed Version Control System

Successor to CVS

Stores and versions:

source code

documentation

anything, really

Installing Subversion

Choose a Protocol

give repo access to local users give users and/or groups read/write on the repo to grant access file:///home/lorna/svn-repos/main/trunk/ Local filesystem

give repo access to local users

give users and/or groups read/write on the repo to grant access

file:///home/lorna/svn-repos/main/trunk/

give repo access to users with ssh credentials give users and/or groups read/write on the repo to grant access svn+ssh svn://rivendell/home/lorna/svn-repos/main/trunk svn+ssh

give repo access to users with ssh credentials

give users and/or groups read/write on the repo to grant access

svn+ssh svn://rivendell/home/lorna/svn-repos/main/trunk

make repo web-browseable and have apache handle credentials basic or digest HTTP authentication (e.g., .htpasswd) mod_authz_svn - an Apache module to give finer access control http://svn.example.com/main/trunk WebDAV via HTTP/S

make repo web-browseable and have apache handle credentials

basic or digest HTTP authentication (e.g., .htpasswd)

mod_authz_svn - an Apache module to give finer access control

http://svn.example.com/main/trunk

Installing on Linux

Debian/Ubuntu: aptitude install subversion Fedora/RedHat: yum install subversion Distribution packages

Debian/Ubuntu: aptitude install subversion

Fedora/RedHat: yum install subversion

download from http://subversion.tigris.org check dependencies (install apache, mod_dav, etc., first) compile From source

download from http://subversion.tigris.org

check dependencies (install apache, mod_dav, etc., first)

compile

Setting up a repository

What is a repository ?

The place all changesets are stored A black box; you may only interact with it using svn tools A repository is...

The place all changesets are stored

A black box; you may only interact with it using svn tools

Creating the repository

Use “svnadmin create”

Create initial content

Commit initial structure

Alternate way: import into the repo

About repository structure

Trunk – the main code version Branches – copies of code which can be modified Tags – copies of code which are never changed All are “cheap” copies Repository Structure

Trunk – the main code version

Branches – copies of code which can be modified

Tags – copies of code which are never changed

All are “cheap” copies

Using Subversion

Checkout: svn checkout (co)

.svn directory

Status: svn status (st)

' ' no modifications 'A' Added 'C' Conflicted 'D' Deleted 'M' Modified '?' item is not under version control '!' item is missing (removed by non-svn command) or incomplete 'X' external resource managed by svn (svn:externals) Common status codes

' ' no modifications

'A' Added

'C' Conflicted

'D' Deleted

'M' Modified

'?' item is not under version control

'!' item is missing (removed by non-svn command) or incomplete

'X' external resource managed by svn (svn:externals)

Add to repo: svn add

Commit to repo: svn commit (ci)

Changelog: svn log

Dealing with missing files

“ !” in the status listing Usually because something was moved or deleted without using the svn tools Always use svn rm and svn mv To fix: update (svn up) and try again Missing files - ! in the status

“ !” in the status listing

Usually because something was moved or deleted without using the svn tools

Always use svn rm and svn mv

To fix: update (svn up) and try again

What and When to commit

hourly, semi-daily, daily checkins code only, tests only, docs only Bad practices

hourly, semi-daily, daily checkins

code only, tests only, docs only

Each commit should include all code, tests, and docs related to a discrete behavior or set of functionality. The Best Practice:

Easy to “cherry-pick” changesets between branches Trivial to identify changesets to rollback Why?

Easy to “cherry-pick” changesets between branches

Trivial to identify changesets to rollback

Examples

Examples

PLAN your project; break it into distinct units of functionality Use an issue tracker; issues should include expectations, actual results, and reproduce code (these become your tests!) No unit of functionality should take more than 3-4 hours to implement; longer, and it likely should be broken into sub-tasks. How?

PLAN your project; break it into distinct units of functionality

Use an issue tracker; issues should include expectations, actual results, and reproduce code (these become your tests!)

No unit of functionality should take more than 3-4 hours to implement; longer, and it likely should be broken into sub-tasks.

Conflicts

svn blame / annotate / praise shows who last edited which line svn blame

svn blame / annotate / praise

shows who last edited which line

Example

Two people change same line of same file svn will ask user to choose Conflicts

Two people change same line of same file

svn will ask user to choose

index.php.r4 version from before either your changes or the commit that has conflicted index.php.r6 current repo version index.php.mine working copy before server showed conflict index.php whole file with some markup to show just the conflict(s) in place Example: conflict adds files

index.php.r4 version from before either your changes or the commit that has conflicted

index.php.r6 current repo version

index.php.mine working copy before server showed conflict

index.php whole file with some markup to show just the conflict(s) in place

edit index.php until correct may copy one of the "extra" files into place of this one let SVN know you're all sorted svn resolved

edit index.php until correct

may copy one of the "extra" files into place of this one

let SVN know you're all sorted

Good team communication Update often Commit first! Avoiding Conflicts

Good team communication

Update often

Commit first!

Branching and Tagging

Patterns

Feature Branches Graph by Eli White

Pros: Features may be developed in isolation Trunk always contains “finished” features Cons: Features may be developed in isolation Hard to cleanly merge at times if multiple features touch the same areas of code Harder to rollback (trunk doesn't always have discrete featuresets) Feature Branches

Pros:

Features may be developed in isolation

Trunk always contains “finished” features

Cons:

Features may be developed in isolation

Hard to cleanly merge at times if multiple features touch the same areas of code

Harder to rollback (trunk doesn't always have discrete featuresets)

Long-lived Branches Graph by Eli White

Pros: Production is always stable Rollback by pointing to production tags Cons: Long-lived feature development often lags trunk features Difficult to determine what to merge Difficult to do parallel feature development More difficult to rollback specific features Long-lived Branches

Pros:

Production is always stable

Rollback by pointing to production tags

Cons:

Long-lived feature development often lags trunk features

Difficult to determine what to merge

Difficult to do parallel feature development

More difficult to rollback specific features

Release Branches Graph by Eli White

Pros: Easy to isolate features by version (parallel development) Possibility of keeping multiple active versions of a project Cons: Harder to merge patches between branches (files may differ widely) Release Branches

Pros:

Easy to isolate features by version (parallel development)

Possibility of keeping multiple active versions of a project

Cons:

Harder to merge patches between branches (files may differ widely)

Merging

Moving changes between branches (including trunk) Merge single changes Merging as part of a branch lifecycle Merging

Moving changes between branches (including trunk)

Merge single changes

Merging as part of a branch lifecycle

Check out the target branch From the target directory, run svn diff until the output illustrates the operation you wanted Replace "diff" with "merge" Review changes to working copy and/or test How to merge

Check out the target branch

From the target directory, run svn diff until the output illustrates the operation you wanted

Replace "diff" with "merge"

Review changes to working copy and/or test

Use “svn log” to identify discrete changesets you want to merge. Use the “cherry-pick” flag of “svn merge” (-c) to merge that single changeset. Works well if you're following the best practices outlined earlier! How to merge: the easy way

Use “svn log” to identify discrete changesets you want to merge.

Use the “cherry-pick” flag of “svn merge” (-c) to merge that single changeset.

Works well if you're following the best practices outlined earlier!

Administering Repositories

Backing up your Repository

Copying files directly can lead to corruption in the copy Use “svnadmin hotcopy” or “svnadmin dump” svnadmin hotcopy

Copying files directly can lead to corruption in the copy

Use “svnadmin hotcopy” or “svnadmin dump”

Authentication

Dependent on how the OS does authentication: Local accounts “ Virtual” accounts etc. SSH public keys are a common solution svnserve or svn+ssh

Dependent on how the OS does authentication:

Local accounts

“ Virtual” accounts

etc.

SSH public keys are a common solution

Typically HTTP basic or digest authentication Use htpasswd to generate user/pass pairs Can still allow anonymous access Configure your server to require it WebDAV (http/https)

Typically HTTP basic or digest authentication

Use htpasswd to generate user/pass pairs

Can still allow anonymous access

Configure your server to require it

Example HTTP Auth configuration

Authorization

Typically conf/authz in your repo, or “access.conf” accessible to web server INI-style file with [sections] [groups] section to define users and groups [/path] specifies path on repo [repo:/path] specifies path on specific repo (if more than one repo defined) ACL File

Typically conf/authz in your repo, or “access.conf” accessible to web server

INI-style file with [sections]

[groups] section to define users and groups

[/path] specifies path on repo

[repo:/path] specifies path on specific repo (if more than one repo defined)

ACLs: [user|group] = [r|rw] “ *” as group/user means any user Groups are prefixed with “@” ACL File

ACLs:

[user|group] = [r|rw]

“ *” as group/user means any user

Groups are prefixed with “@”

ACL File: example

Svnserve, file access, or svn+ssh: conf/authz in your repository WebDAV: anywhere. Tell your vhost where to find it Must setup authorization prior to authentication ACL File: placement

Svnserve, file access, or svn+ssh: conf/authz in your repository

WebDAV: anywhere.

Tell your vhost where to find it

Must setup authorization prior to authentication

ACL File in WebDAV: vhost setup

Hooks

Allow extending SVN's capabilities via userland scripts “ Hook” into specific processes: pre/post-commit, start-commit pre/post-revprop-change pre/post-lock pre/post-unlock What are hooks?

Allow extending SVN's capabilities via userland scripts

“ Hook” into specific processes:

pre/post-commit, start-commit

pre/post-revprop-change

pre/post-lock

pre/post-unlock

Running a linter REPOS = "$1" TXN = "$2" PHP = "/path/to/php" SVNLOOK = "/path/to/svnlook" AWK = "/path/to/awk" GREP = "/path/to/egrep" SED = "/path/to/sed" CHANGED = `$SVNLOOK changed -t "$TXN" "$REPOS" | $AWK '{print $2}' | $GREP \.php$` for FILE in $CHANGED do MESSAGE = `$SVNLOOK cat -t "$TXN" "$REPOS" "$FILE" | $PHP -l` if [ $? - ne 0 ] then echo 1 >& 2 echo "***********************************" 1 >& 2 echo "PHP error in: $FILE:" 1 >& 2 echo `echo "$MESSAGE" | $SED "s| -| $FILE|g"` 1 >& 2 echo "***********************************" 1 >& 2 exit 1 fi done

*********************************** PHP error in: test.php echo $foobar *********************************** Sample linter output

Run post-commit – prevents blocking issues Send email notification when tests fail Two approaches: Run entire suite Grep committed files for classes, and test just those classes Typically best to do this from a Continuous Integration server, and not via subversion hooks Running unit tests

Run post-commit – prevents blocking issues

Send email notification when tests fail

Two approaches:

Run entire suite

Grep committed files for classes, and test just those classes

Typically best to do this from a Continuous Integration server, and not via subversion hooks

Email, Nabaztag, TwitterSVN Email notifications post-commit SVN::Notify: http://search.cpan.org/~dwheeler/SVN-Notify-2.79/lib/SVN/Notify.pm Can selectively determine which people/lists get notifications based on commit path Plain text and/or HTML emails Sending notifications

Email, Nabaztag, TwitterSVN

Email notifications post-commit

SVN::Notify:

http://search.cpan.org/~dwheeler/SVN-Notify-2.79/lib/SVN/Notify.pm

Can selectively determine which people/lists get notifications based on commit path

Plain text and/or HTML emails

Example notification:

svn2feed.py: http://svn.collab.net/repos/svn/trunk/tools/hook-scripts/svn2feed.py Add svn2feed.py to your hooks/ directory Publishing RSS Feeds

svn2feed.py: http://svn.collab.net/repos/svn/trunk/tools/hook-scripts/svn2feed.py

Add svn2feed.py to your hooks/ directory

Adding svn2feed.py to your post-commit hook: path / to / python path / to / hooks / svn2feed.py -- svn - path / usr / bin / -- max - items = 100 -- format = atom -- revision "$REV" – item - url "http://localhost/svn/" -- feed - url = "http://localhost/rss/svn.rss" -- feed - file "path/to/rss/svn.rss" "$REPOS" &

Trigger docbook build process, or PhpDocumentor Run post-commit, so as not to block Typically best done from a CI server, and not subversion hooks Generating documentation

Trigger docbook build process, or PhpDocumentor

Run post-commit, so as not to block

Typically best done from a CI server, and not subversion hooks

PHP_CodeSniffer includes a script, bin/scripts/phpcs-svn-pre-commit Edit the script to provide the path to svnlook: define('PHP_CODESNIFFER_SVNLOOK', '/usr/bin/svnlook'); Edit the pre-commit hook script to invoke the script: /path/to/bin/scripts/phpcs-svn-pre-commit "$REPOS" -t "$TXN" >&2 || exit 1 Running PHP_CodeSniffer

PHP_CodeSniffer includes a script, bin/scripts/phpcs-svn-pre-commit

Edit the script to provide the path to svnlook:

define('PHP_CODESNIFFER_SVNLOOK', '/usr/bin/svnlook');

Edit the pre-commit hook script to invoke the script:

/path/to/bin/scripts/phpcs-svn-pre-commit "$REPOS" -t "$TXN" >&2 || exit 1

Transmitting file data .svn: Commit failed (details follow): svn: 'pre-commit' hook failed with error output: FILE: temp.php --------------------------------------------------------------- FOUND 1 ERROR(S) AND 0 WARNING(S) AFFECTING 1 LINE(S) --------------------------------------------------------------- 2 | ERROR | Missing file doc comment -------------------------------------------------------------- PHP_CodeSniffer hook output

Transmitting file data .svn: Commit failed (details follow):

svn: 'pre-commit' hook failed with error output:

FILE: temp.php

---------------------------------------------------------------

FOUND 1 ERROR(S) AND 0 WARNING(S) AFFECTING 1 LINE(S)

---------------------------------------------------------------

2 | ERROR | Missing file doc comment

--------------------------------------------------------------

http://pear.php.net/manual/en/package.php.php-codesniffer.svn-pre-commit.php For more info on PHP_CodeSniffer:

http://pear.php.net/manual/en/package.php.php-codesniffer.svn-pre-commit.php

Deploying from SVN

What else needs to happen at deploy time? Preserve uploads Set permissions Database patches Deployment Considerations

What else needs to happen at deploy time?

Preserve uploads

Set permissions

Database patches

Checkout retains link to repo Meta data present on server Inconsistent state during update Export is clean copy, no dependencies Other ways to keep track of version Checkout or Export

Checkout retains link to repo

Meta data present on server

Inconsistent state during update

Export is clean copy, no dependencies

Other ways to keep track of version

Tag and export from svn – include some tag info Use symlinks to enable seamless switching Wrap in a script Have a rollback plan/script Consider database strategies Best Practices

Tag and export from svn – include some tag info

Use symlinks to enable seamless switching

Wrap in a script

Have a rollback plan/script

Consider database strategies

Thank you.