oweierphinney-2009-05-19-svnforphpdevs-090519165923-phpapp01

7/27/2019 oweierphinney-2009-05-19-svnforphpdevs-090519165923-phpapp01

http://slidepdf.com/reader/full/oweierphinney-2009-05-19-svnforphpdevs-090519165923-phpapp01 1/93

Practical SVNfor PHP Developers

Matthew Weier O'PhinneyProject Lead

Zend Framework

Lorna Jane MitchellSoftware Engineer

Ibuildings



What isVersion 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 isSubversion?



• Non-Distributed Version Control System

• Successor to CVS

• Stores and versions: – source code

– documentation

– anything, really

Subversion is...



InstallingSubversion



Choose a Protocol



• give repo access to local users

• give users and/or groups read/write on therepo to grant access

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

Local filesystem



• give repo access to users with sshcredentials

• give users and/or groups read/write onthe repo to grant access

• svn+ssh svn://rivendell/home/lorna/svn-

repos/main/trunk

svn+ssh



• make repo web-browseable and haveapache handle credentials

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

• mod_authz_svn - an Apache module togive finer access control

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

WebDAV via HTTP/S



Installingon Linux



• Debian/Ubuntu:

aptitude install subversion• Fedora/RedHat:

yum install subversion

Distribution packages



• download fromhttp://subversion.tigris.org

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

• compile

From source



Setting up arepository



What is arepository ?



• The place all changesets are stored

• A black box; you may only interact with itusing svn tools

A repository is...



Creating therepository

U “ d i ”



Use “svnadmin create”

C t i iti l t t



Create initial content

C it i iti l t t



Commit initial structure

Alt t i t i t th



Alternate way: import into the repo



About

repositorystructure

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)



Checkout: svn checkout (co)

svn directory



.svn directory

Status: svn status (st)



Status: svn status (st)

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)

Common status codes

Add to repo: svn add



Add to repo: svn add

Commit to repo: svn commit (ci)



Commit to repo: svn commit (ci)

Changelog: svn log



Changelog: svn log



Dealing withmissing files

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

Missing files ! in the status



What and Whento commit

Bad practices



•

hourly, semi-daily, daily checkins• code only, tests only, docs only

Bad practices

The Best Practice:



Each commit should include all

code, tests, and docs relatedto a discrete behavior or set of functionality.

The Best Practice:

Why?



• Easy to “cherry-pick” changesets

between branches• Trivial to identify changesets to rollback

y

Examples



p

Examples



p

How?



• PLAN your project; break it into distinct units of functionality

• Use an issue tracker; issues should include

expectations, actual results, and reproducecode (these become your tests!)

• No unit of functionality should take more than3-4 hours to implement; longer, and it likely

should be broken into sub-tasks.



Conflicts

svn blame



•

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

Example



Conflicts



• Two people change same line of same

file• svn will ask user to choose

Example: conflict adds files



• index.php.r4 version from before either yourchanges or the commit that has conflicted

• index.php.r6 current repo version

• index.php.mine working copy before servershowed conflict

• index.php whole file with some markup to

show just the conflict(s) in place

svn resolved



• edit index.php until correct

•

may copy one of the "extra" files intoplace of this one

• let SVN know you're all sorted

Avoiding Conflicts



• Good team communication

• Update often• Commit first!



Branchingand Tagging



Patterns

Feature Branches



Graph by Eli White



Long-lived Branches



Graph by Eli White

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

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

Merging



• Moving changes between branches(including trunk)

• Merge single changes

• Merging as part of a branch lifecycle

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

How to merge: the easy way



• Use “svn log” to identify discretechangesets you want to merge.

• Use the “cherry-pick” flag of “svn

merge” (-c) to merge that singlechangeset.

• Works well if you're following the best

practices outlined earlier!



AdministeringRepositories



Backing upyour Repository

svnadmin hotcopy



• Copying files directly can lead tocorruption in the copy

• Use “svnadmin hotcopy” or

“svnadmin dump”



Authentication

svnserve or svn+ssh



●Dependent on how the OS doesauthentication:

−Local accounts−“Virtual” accounts−etc.

●

SSH public keys are a common solution

WebDAV (http/https)



● Typically HTTP basic or digestauthentication

−Use htpasswd to generate user/passpairs

−Can still allow anonymous access−Configure your server to require it

Example HTTP Auth configuration



Authorization

T i ll f/ th i

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

ACL File



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

ACL File: example



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 toauthentication

ACL File in WebDAV: vhost setup



Hooks

What are hooks?



●

Allow extending SVN's capabilities viauserland 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

Sample linter output



***********************************PHP error in: test.phpecho $foobar ***********************************

R t it t bl ki i

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 subversionhooks

●Email Nabaztag TwitterSVN

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 whichpeople/lists get notifications based on

commit path−Plain text and/or HTML emails

Example notification:



Publishing RSS Feeds



• svn2feed.py:http://svn.collab.net/repos/svn/trunk/tools/ho

ok-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" &

Generating documentation



• Trigger docbook build process, orPhpDocumentor

•

Run post-commit, so as not to block• Typically best done from a CI server, and

not subversion hooks

PHP C d S iff i l d i

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

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

PHP_CodeSniffer hook output



Transmitting file data .svn: Commit failed (detailsfollow):

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

For more info on PHP_CodeSniffer:



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



Deploying from SVN

Deployment Considerations



• What else needs to happen at deploytime?

•

Preserve uploads• Set permissions

• Database patches

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

Best Practices



•

Tag and export from svn – includesome tag info

• Use symlinks to enable seamless

switching• Wrap in a script

• Have a rollback plan/script

•

Consider database strategies



Thank you.

oweierphinney-2009-05-19-svnforphpdevs-090519165923-phpapp01

Documents