Document Actions
2.3.
Version control
Up one level
It is important that you familiarise yourself with subversion before committing to the Plone source repository, to reduce the risk of accidental screw-ups. The Subversion book is a comprehensive, but surprisingly accessible resource.
Setting up your environment
There is a list of non-command line clients which you might find easier to use than the standard command line client. If you are a developer from the Windows platform, we highly recommend the excellent TortoiseSVN product instead of the "standard" command line client.
Note that we are following the same policy as svn.zope.org regarding setup for line endings, please read SVN Configuration for line endings
Getting the source code
Development versions of Plone are managed in Subversion bundles. A bundle is simply a set of top-level modules that must be checked out. In general, you can check out a bundle into the Products/ directory of your Zope instance, run any external scripts needed to get resources not available in svn (such as getExternalEditor.sh), and start Zope. The bundles are found in https://svn.plone.org/svn/plone/bundles/.
At the time of writing, the 2.5 bundle contains the current development version of Plone. You can check this out by doing:
svn co https://svn.plone.org/svn/plone/bundles/2.5 ./getExternalEditor.sh
Commits
You should make one change per commit. If you are fixing three bugs, make three commits. That way, it is easier to see what was done when, and easier to roll back any changes if necessary. Also, large, monolithic commits are very difficult to read. Yes - people do read the checkin list to see what happens to their favourite CMS! If you want to make large changes cleaning up whitespace or renaming variables, it is especially important to do so in a separate commit.
It is a cardinal sin to commit any change without properly testing it with unit tests, as well as in the browser (see next page). Please review your code for silly mistakes, lingering pdb statements, debugging print statements or any other junk that shouldn't be there.
ALWAYS run all the Plone unit tests before commiting (see next page). There is NO exception to this rule. If you submit code that breaks a test, your change will almost certainly be reverted with a terse note to plone-dev. If you are at all in doubt, please also run the ATContentTypes and Archetypes unit tests, at the very least.
Before commiting any bugfix or feature enhancement, you must also add a note in Plone's HISTORY.txt. Follow the convention in that file, and note your name in brackets. This file is used to clarify what new features have been added when a new release is made, and should be an accurate account of the changes you have made.
Checkin messages
It is vital that you write proper checkin messages. A checkin message should inform the reader what was done, and why. If a bug was closed, the bug number should be included, e.g.:
Added the plone_deprecated skin layer back into migration. Fixes #1234.
The "Fixes #1234" will actually cause bug #1234 to be marked as closed in the bug tracker automatically.
Using branches for non-trivial changes
If you are doing anything non-trivial, changes should go on a branch! See also the page on the PLIP process. A svn branch is simply a copy of the existing development version that you can work on undisturbed. When your work is finished, tested and approved, the branch can be merged back.
It is important that you name your branch so that people can easily see who is working on it, and what it is for. For example, to branch CMFPlone trunk to work on refactoring foobar, I could write:
svn up # update to the latest revision beforehand
svn info # find out which revision you are branching from
svn cp https://svn.plone.org/svn/plone/CMFPlone/trunk \
https://svn.plone.org/svn/plone/CMFPlone/branches/optilude-2.5-foobar-refactoring
The checkin message for this operation must be informative, and must include the revision number of the branch you started from:
Branched Plone trunk r1234 to begin work on foobar refactoring.
Switching to an existing branch, for example if you want to test someone else's code, is also very simple:
cd CMFPlone./ svn switch https://svn.plone.org/svn/plone/CMFPlone/branches/optilude-2.5-foobar-refactoring
Never create a branch directly from your working directory. Copy it from the repostitory instead: "svn cp original_url branch_url". If you have changes in your working copy that sould be included in the new branch switch to it and commit (after checking for conflicts).
When a branch is ready to be merged, notify the release manager. If you are merging yourself, it is important that you include which revisions you merged in your checkin message:
Merged optilude-2.5-foobar-refactoring branch r1234:1245 into trunk.
Note the format of the range of revisions (r1234:1245). Please follow this format exactly, as it will make the job of the release manager much easier should there be a problem.
Please do not rename or move branches unless absolutely necessary - Subversion is not very good at handling this. Again, include the revision numbers of what you renamed or moved in the checkin message if you must do this. The reason for this is that the only way to find out where to branch from is to use svn log --stop-on-copy, which will reveal which revision the branch was originally copied from. When you rename or move a branch, this command will stop on the revision where the rename or move happened.
Using bundles for code review
When you are sponsoring a PLIP or wish to demonstrate some new feature, you should make life easier for the framework team, the release manager and the general public by using review bundles. A review bundle should work as the main development bundles do: Another developer should be able to check it out into the Products/ folder of a fresh Zope instance and see exactly what changes have been implemented, immediately.
To create a bundle, first create the necessary branches on the modules you are changing, and set up a sandbox that contains only the relevant checkouts. If the code is a moving target, packages are bundled at the revision that the developer wants reviewed.
All bundles must include:
- A README.txt in the root including any caveats or explanation necessary.
- A COMMENTS.txt for developers to record comments
- TODO.txt for recording things that need to be done
- The bundle must compile and run upon checkout!
A bundle is managed using a file in the root of the bundle, conventionally called EXTERNALS.txt. You should use the EXTERNALS.txt of your development bundle checkout as a starting point. Then, to create a new bundle, you do:
svn mkdir https://svn.plone.org/svn/plone/review/plip1234-my-crazy-feature-bundle svn co https://svn.plone.org/svn/plone/review/plip1234-my-crazy-feature-bundle my-bundle cd my-bundle svn propget svn:externals > EXTERNALS.txt # edit the file, changing any svn paths to point to the relevant branches svn propset svn:externals -F EXTERNALS.txt . svn commit
You can now test this by doing:
mkdir bundle-test cd bundle-test svn co https://svn.plone.org/svn/plone/review/plip1234-my-crazy-feature-bundle
This should include all the necessary products to start a Zope site demonstrating your new feature.
