Subversion Standards

h1. Zend Framework Subversion Standards

h2. What is Subversion?

"SVN (Subversion) is a tool used by many software developers to manage changes within their source code tree. SVN provides the means to store not only the current version of a piece of source code, but a record of all changes (and who made those changes) that have occurred to that source code. Use of SVN is particularly common on projects with multiple developers, since SVN ensures changes made by one developer are not accidentally removed when another developer posts their changes to the source tree." --sourceforge.net

For more information, please visit the [official Subversion site|http://subversion.tigris.org/].

h2. The Zend Framework Subversion Repository

The Zend Framework is an open source project, and the complete source code can be downloaded anonymously by direct checkout from its Subversion repository. For information on how to receive automatic notification of changes and updates to the Zend Framework and documentation, please see [RSS Feeds and Notifications].

Also see these [examples|Submitting a Bug Fix] showing how to make patches.

h3. Anonymous Checkout

The most up-to-date working copy of the Zend Framework is the trunk. This includes all the newest features and bugfixes and incubator components. However, the latest versions of each file often have far less testing, and may or may not have fewer bugs than the versions found in the most recently released, stable version of Zend Framework in the [download area|http://sandbox.zend.com/download/].

{code:title=SVN Checkout}
svn checkout http://framework.zend.com/svn/framework/standard/trunk
# ZF Lab, see http://framework.zend.com/wiki/display/ZFPROP/Home
svn checkout http://framework.zend.com/svn/framework/laboratory/
{code}

Please report new bugs, submit patches, or comment on posted issues using the [Issue Tracker|http://framework.zend.com/issues].

h3. Anonymous Checkout using MS Windows

# Install [TortoiseSVN|http://tortoisesvn.tigris.org/] and restart your computer
# Create a new folder called "ZendFramework-trunk"
# Right click on the new folder, choose "SVN Checkout", and enter this URL: http://framework.zend.com/svn/framework/standard/trunk/
# The Zend Framework core components will be in the subfolder "library" inside of the "ZendFramework-trunk" folder.
# Incubator components (see next section) will be in the subfolder "incubator" inside of the "ZendFramework-trunk" folder.
# Before reporting bugs, first update your downloaded copy of the framework by right-clicking on the "ZendFramework-trunk" folder and selecting "SVN Update".
# Repeat for the ZF Lab with the URL: http://framework.zend.com/svn/framework/laboratory/

h3. Using the Zend Framework Incubator Components

Follow the procedure above for "Anonymous Checkout". After proposals for new components or major rewrites of existing components have been accepted, the new components are first placed into the "incubator":
http://framework.zend.com/svn/framework/standard/incubator/

When incubator components are considered sufficiently mature and stable enough, then they are moved into the normal location for Zend Framework components. Incubator components are not bundled with the Zend Framework download, but are included with the Subversion download/checkout process.

Those wishing to use incubator components, may use them by modifying PHP's include path:
{code}set_include_path( '/path/to/incubator/library' . PATH_SEPARATOR
. '/path/to/library' . PATH_SEPARATOR
. get_include_path());{code}

See also the [Zend Framework Proposal Process|http://framework.zend.com/wiki/display/ZFPROP/Home].

h3. Prior Release Versions

All versions of the Zend Framework that are released to the public are tagged and also available for download from the repository. Checkout or export http://framework.zend.com/svn/framework/ and check the tags directory for previous releases.

h3. Using Subversion from behind a Proxy / Firewall

*Squid:* If svn does not work on your lan, and you have a Squid Proxy (ask your IT staff), then try adding these 3 lines of code to the Squid Proxy's squid.conf file:
{code}/
extension_methods REPORT MERGE MKACTIVITY CHECKOUT /
//{code}

h2. Subversion Write / Commit Access

Frequently, suggesting and making changes works best when [attaching a patch to an issue|http://framework.zend.com/wiki/x/8wU] in our [issue tracker|http://framework.zend.com/issues/]. The community will have an opportunity to review your patch, comment on your notes in the issue ticket, and make suggestions. Then, you can review these comments and possibly make improvements to the patch, before it is committed.

h3. SVN Access

Write access to SVN is granted to component and project team coordinators and higher volume contributors. If you need access to SVN, you may request it on the mailing list or through a coordinator that you have worked with previously, however appropriate. In general, we do not grant SVN access to anyone who signs a CLA. There are additional criteria used to determine whether a person needs SVN access. Even in cases where SVN access is granted, it is typically limited to one or more focus areas, and component and project team coordinators will be responsible for managing commits by other team members having SVN access.

You do not need an SVN account in order to make contributions to the Zend Framework, however, as we gladly accept feedback on the mailing list and patches to be submitted via our issue tracker. If indeed you are interested in collaboration, we recommend reading and providing feedback over the fw-general mailing list, where most collaboration takes place each day.

You may also submit a proposal (after discussing such on the mailing list), and upon its approval you would receive limited SVN access to facilitate adding the proposed code, unit tests, and documentation.

h3. SVN Usage Rules

A few rules should be kept in mind when using SVN:

* All commits should contain commit comments.
* If a commit is resolving an issue from the issue tracker, the issue KEY should be indicated in the commit comment (i.e. "This resolves ZF-2"). This will cause it to be auto-linked from Fisheye to the issue, and also the reverse link from the issue back to Fisheye. The issue key can be seen when viewing any issue in the upper left corner of the screen.
* All commits that would affect release notes should have an associated issue in the tracker. There are issue types for most situations, and if it is just a significant change that does not fit into another category, use the issue type "Patch."
* When resolving an issue, feel free to edit the issue's title to be clearer based on anything you learned while fixing it. This will aid the readability of the release notes.
{code:title=Create new dirs for new proposal}
svn checkout http://framework.zend.com/svn/framework/standard/trunk
cd trunk
mkdir ./incubator/library/Zend/<component name>
touch ./incubator/tests/Zend/<component name>Test.php
mkdir ./incubator/tests/Zend/<component name>
mkdir ./incubator/demos/Zend/<component name>
svn add ./incubator/library/Zend/<component name>.php \
./incubator/library/Zend/<component name> \
./incubator/tests/Zend/<component name>Test.php \
./incubator/tests/Zend/<component name> \
./incubator/demos/Zend/<component name>
svn commit ./incubator/library/Zend/<component name>.php \
./incubator/library/Zend/<component name> \
./incubator/tests/Zend/<component name>Test.php \
./incubator/tests/Zend/<component name> \
./incubator/demos/Zend/<component name> \
-m 'Initial setup for new component: <component name>'
{code}
* When merging, include the SVN revision(s) being merged and the identifiers of related [JIRA|http://framework.zend.com/issues] issues in your commit message, as in the following:
{code:title=Composing a commit message for a merge}
Merged r8468 from trunk; resolves ZF-2100
{code}

h3. Tip - SVN auto-props

In your SVN client config file (e.g. ~/.subversion/config) you can use the following settings to automatically set svn:keywords=Id on PHP files that you add to the framework repository. This doesn't work for files that already exist in SVN, of course, but it may be useful:

{code}
enable-auto-props = yes

[auto-props]
*.php = svn:keywords=Id
{code}

We added the "Id" keyword to most files in the ZF SVN repository in changeset 1605:

This instructs Subversion to substitute $<keyword>$ with certain information. Prior to committing, Subversion unsubstitutes the keywords (to prevent artificial differences arising) in order to prevent recording artificial differences. Then, Subversion updates the files with values substituted for these keywords. These keywords (Id Author Date Rev) help to keep track of meta information on each file, even after exporting. Thus, even the snapshot releases contain the following information in each file that has an $Id$ keyword, and the corresponding SVN properties set on that file:

Revision: This keyword describes the last known revision in which this file changed in the repository,
Date: This keyword describes the last time the file was known to have been changed in the repository
Author: This keyword describes the last known user to change this file in the repository,
Id: This keyword is a compressed combination of the other keywords.

When you add a new file, simply make sure to copy the following into the top of the file:
{code:php}
<?php
/**
* Zend Framework
*
* LICENSE
*
* This source file is subject to the new BSD license that is bundled
* with this package in the file LICENSE.txt.
* It is also available through the world-wide-web at this URL:
* http://framework.zend.com/license/new-bsd
* If you did not receive a copy of the license and are unable to
* obtain it through the world-wide-web, please send an email
* to license@zend.com so we can send you a copy immediately.
*
* @category Zend

*/
{code}

h3. Merging changes

Merging is a fundamental software configuration management (SCM) operation, and merging is often used for Zend Framework release maintenance. For example, suppose Joe commits a change to the trunk (revision 42), after he confirms that tests are passing, but he asks Sally, another contributor, to review and test his changes for quality assurance before merging to the STABLE branch. Sally confirms that the tests pass on her system and gives the "ok", and now Joe needs to merge his change to the STABLE branch. How does he do it?

Using the command line interface to SVN, it is quite simple to merge a single revision:
{noformat}
$ cd /path/to/framework/branch/STABLE # Operate within the directory that is to receive the change

$ svn merge -c 42 http://framework.zend.com/svn/framework/standard/trunk # Merge revision 42 from the trunk

$ svn ci # Commit the change, and in the commit message indicate that r42 was merged from the trunk
{noformat}

For more information about merging in SVN, please review the output of "{{svn help merge}}", and take a look at the [documentation|http://svnbook.red-bean.com/en/1.4/svn.ref.svn.c.merge.html].

h3. How often should code be committed to the Subversion repository?

h4. Released Components (including released incubator components)

Avoid breaking existing functionality.

Commit your changes as often as code is completed and tested successfully. No code should enter the repository that is not tested, but you also may not want to hold off on committing large chunks of work that are incomplete, and in this case, interstitial commits should be acceptable, so long as they do not break existing functionality.

h4. Unreleased Incubator Components

Prior to the first public release of an incubator component, incubator contributors should commit early and often, regardless of unit tests and documentation completion. Indeed, documentation will require reworking as often as the API changes, and it is unnecessary to have to do this reworking for incubator components not yet selected for release in the core framework. Although most consider testing while developing best practice, it is more important that code enter the repository on a daily basis for enabling review and continuous work by other framework contributors. That is, incubator contributors should commit their outstanding work on a daily basis, whether it is "complete" or not, until the component is selected for inclusion with a public release of the Zend Framework (including a publicly released incubator component). After the time when a component is selected for release, the more strict policy of committing only unit-tested code would apply, and the API should stabilize enough for writing documentation to be included with the release.


\\