Practical SVN for PHP Developers

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

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

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

What is Subversion?

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

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 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

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

Installing on Linux

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

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

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...

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

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

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

What and When to commit

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

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?

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?

Conflicts

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

Example

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

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

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

Good team communication
Update often
Commit first!
Avoiding Conflicts

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

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

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

Merging

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

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

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

Administering Repositories

Backing up your Repository

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

Authentication

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

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)

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

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

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

ACL File in WebDAV: vhost setup

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?

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

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

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

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

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

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

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

Deploying from SVN

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

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

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

Thank you.

http://www.lornajane.net	1090
http://www.slideshare.net	22
http://beta.lornajane.net	2
http://www.techgig.com	2
http://twitter.com	1
http://translate.googleusercontent.com	1

Practical SVN for PHP Developers

by Lorna Mitchell on May 19, 2009

Accessibility

Categories

Tags

Upload Details

Usage Rights

6 Embeds 1,118

Statistics

Practical SVN for PHP Developers — Presentation Transcript