ZopeSVNFAQ

If you are new to subversion, the fist thing you should do is to read the first four chapters of the subversion book .

This FAQ is an attempt to gather together much of the common wisdom for how developers (both internal and external) work with the Zope sources in Subversion. Many of the items apply to other areas in the Zope repository, in addition to the Zope area.

But I don't know anything about subversion...!
The subversion book provides an excellent introduction to subversion. There is also a chapter for those who are already familiar with CVS
Where can I get a client for my favourite OS?
You can find the sources and packages for RedHat, SuSE, Mandrake, FreeBSD, and Windows at the subversion download homepage.

Subversion is also available in Debian GNU/Linux (apt-get install subversion) as well as in Fink for MacOSX? ( View all available packages . To install the client binary package: apt-get install svn-client-ssl ).

If you're using Windows and would like to have integration into the Windows Explorer, take a look at TortoiseSVN.
How should I configure subversion
It is VERY IMPORTANT that you configure subversion to set line endings. See SubversionConfigurationForLineEndings

When you are configuring subversion to set line endings, you should probably also set subversion to ignore .pyc and .pyo files by setting the global-ignores option in your subversion configuration file.
Can I get to the repository from a web browser
Of course: http://svn.zope.org/
How do I check out Zope?
Most people have read-only access - see ReadOnlyAccess for instructions:
```
      svn co svn://svn.zope.org/repos/main/Zope/trunk Zope
```
For those with write privileges, see WriteAccess. The quick hint, if you've got all the incidentals in place (and replacing myaccount with your zope.org account name):
```
      svn co svn+ssh://[email protected]/repos/main/Zope/trunk Zope
```
Note that if your client user name is the same as your zope.org account name, you can omit the account name from the URL.

See the important note on SubversionConfigurationForLineEndings.
What are revision numbers?
Subversion assigns revision numbers to the repository as a whole. When you check in a change to subversion, you are incrementing the revision number for the respository as a whole.

See: http://svnbook.red-bean.com/svnbook/ch02s03.html#svn-ch-2-sect-3.2
Why do examples sometimes use svn URLs and sometimes use svn+ssh URLs ?
If you have write access to the subversion repository, you can use svn+ssh URLs all the time, however, when you are doing a read-only operation, you can use svn URLs, which happens to be a bit faster, puts less load on the server, and requires less typing. When doing things like logs and diffs using server data, we'll generally use svn URLs.
What do you mean by "the trunk"?
The trunk is the main line of development from which major Zope releases are made. It is very important that the trunk remain stable so that releases can be made on short notice. To keep the trunk from becoming unstable, all work on Zope 2 is done on branches and when the work has stabilized it can be merged into the trunk.

For more information on this see the ZopeReleasePolicy document, which talks more about how our releases are made and why it is important for the trunk to remain stable.

Note that Zope 3 uses a slightly different approach. The trunk must always be stable. We use extensive automated testing to assure that the trunk is always stable. All code checked in must have automated tests and all zope automated tests must be run without error before checking anything in on the trunk. Because of these practices, most development in Zope 3 actually takes place on the trunk. See the last FAQ for more information.
So does that mean I shouldn't check things directly into the Zope 2 trunk?
Right - for Zope 2 we are using the "activity branch" model for coordinating work on the Zope core. This means that you make a new branch to work on a given "activity" (like add a set of features or fixing bugs). When the work is complete, tested and stable the changes in that activity branch are merged into the trunk (and possibly into another branch from which third-dot bug fix releases are made).

More information on the activity branch pattern (as well as a lot of good info on configuration management in general) is available at Streamed Lines.
Ok, so when am I supposed to make a branch in Zope 2?
For Zope 2, any discrete activity that will result in code changes should have its own branch. For example, "adding FTP and DAV support to SQLMethods?" is a feature-adding activity and a branch should be made for it. "Fixing bugs in MailHost?" is an example of a bug-fixing activity that should be done on a branch. Even "fixing collector issue #2020" can be an activity that is on a branch.
What? Make a branch for a single bug fix? Are you licking toads?
It may seem like overkill, especially if you are new to using branches to coordinate a large amount of activity in a codebase, but you find in practice that this will actually make your life easier, not harder. Why? Suppose there is this bug that you want to fix. You cannot just check out the trunk, commit the fix and forget it. The reason you can't is that there is usually another branch besides the trunk that incremental bug-fix releases are being made from, and that branch needs to get the bug fix too.

Technically you could check out a sandbox on the current major-release branch and commit the fix on that branch by hand just like you did for the trunk. In practice it is very easy to make mistakes doing it this way. Once you get the hang of working on branches and merging your work into other branches you will find that it is much faster and much less error-prone to make even small changes by doing them in an activity branch.
Can I work on both bug-fixes and features in the same activity branch?
It is almost always best to seperate bug-fix and new feature work into separate branches. The reason is that new features (once they are tested and stable) should be merged into the trunk only. Bug fixes need to be merged into both the trunk and the current release branch (so that subsequent incremental bug-fix releases will include them). While it is not impossible to do selective (file-by-file) merging to make sure that bugs and features get merged into the right places, it is much easier to just use separate branches.
How do I find out what the current release branch is?
A new "release branch" is created when a new-feature release of Zope goes into its first beta. The name of the release branch created is based on major and minor version numbers of the release. For example, when Zope 2.8 goes into beta, a branch named Zope-2.8 is created and subsequent releases in the 2.8 line are created from the Zope-2.8 branch. You can usually do:
```
      svn ls svn://svn.zope.org/repos/main/Zope/branches
```
to get a list of the branches and see the highest Zope-x.y tag listed to figure out the current release branch. If you are not sure, ask someone!

So how do I make a branch for my work?

See: http://svnbook.red-bean.com/svnbook/ch04.html .

To create a sandbox on an activity branch, copy the trunk to a branch:

      svn copy -m 'Making Zope 2.8 branch' \
        svn+ssh://[email protected]/repos/main/Zope/trunk \
        svn+ssh://[email protected]/repos/main/Zope/branches/mybranchname

Then checkout your branch:

      svn co svn+ssh://[email protected]/repos/main/Zope/branches/mybranchname

How should I name branches I create?
The convention that we want to use is that your name, and a descriptive element be used in branch names. Using your name or login id as part of your branch tag names will help avoid name collisions. Some examples of good branch names:
```
      brian-dav_level2_support
      amos-new_help_system
      jim-zclass_armegeddon
```
How do I check out a sandbox on an existing branch?
See: http://svnbook.red-bean.com/svnbook/ch04.html .

Just give the path top the branch:
```
      svn co svn+ssh://[email protected]/repos/main/Zope/branches/branchname
```
How do I do my work on the branch?
You work in your branch in the same way you would work in any sandbox. You make your changes and use svn commit to commit your changes. When you commit on a branch, the changes are only committed to that branch. The changes won't be visible in the trunk or in other branches until you explicitly merge the changes from your branch into them.
When should I merge changes I've made on a branch?
When the changes you have made are stable and tested, you are ready to merge them to the appropriate places. Exactly where you should merge them will depend on the nature of the activity. If you were working on bug fixes, you will need to merge your work into the current release branch and the trunk. If you were working on new features you probably only need to merge into the trunk.

Before merging anything substantial into the trunk or another branch, make sure that you contact the person responsible for the area you are merging into. This is very important. Subversion gives us a set of tools for coordinating things on a bit level, but communication is key to making sure that things are coordinated in a sane way.

Bad things will happen if you don't let people know what you are doing. If a branch owner has spent two hours reconciling the branch with other things and you start merging in your changes in the middle of this without telling him he is going to be very unhappy with you :) Always coordinate your merges with the owner of the branch you are merging into.
Ok, my changes are stable and tested and the trunk owner said go ahead and merge them. How do I merge changes I've made on a branch into the trunk?
See: http://svnbook.red-bean.com/svnbook/ch04.html .

You will use the svn merge command to merge your changes from the branch. The first thing you'll need to know is the revision in which the branch was created. If you have a check out of the branch, you can cd to the checkout directory and:
```
      svn log --stop-on-copy
```
This tells subversion to list the changes made in the directory from the last copy to the "BASE" revision for the directory, which is the last revision in which the directory changed. The --stop-on-copy option tells subversion to stop outputting entries from before the branch was created. You will generally see one log entry, which is the entry for the branch creation. That tells you the revision number.

By the way, to see all of the changes made on a branch within a directory, use:
```
      svn log -r HEAD:0 --stop-on-copy
```
When you know your revision number, you are ready to merge the changes from the branch. Change to a working directory that you want to merge the changes into, then:
```
       svn update
```
This makes sure that the working copy you merge into is up to date. It also outputs the current revision number, which you will need later. Now, knowing the branch and current revision numbers, you can merge:
```
       svn merge -r rev1:rev2 \
           svn+ssh://[email protected]/repos/main/Zope/branches/yourbranch
```
where rev1 is the revision number you got from the log command, and rev2 is the current revision, output by the update command.

When you perform a merge, be alert for subversion conflict messages. If any conflicts arise, you must resolve the conflicts manually. After you have done the merge and resolved conflicts, test in the sandbox to make sure that things still work as you expect.

When you commit, it is very important to include the merge information in your log message:
```
      svn commit -m 'Merged Zope/branches/yourbranch rev1:rev2'
```
Where rev1 and rev2 are the revision numbers you gave to the merge command.
How would I merge the second batch of work from that branch?
Almost the same as before. Say we've done some more work in our branch and we're ready to merge again. The difference is that we want to merge only changes made since we merged before. You will need to use svn log to find the log message from when you last merged. You need to run svn log for the target of the merge. That is, change to the working directory you will be merging into and do something like:
```
      svn log|grep -i merge      
```
That log message will tell you the last revision you merged. Let's call this rev2. Then, as before. cd to the directory you want to merge into and:
```
       svn update
       svn merge -r rev3:rev4 \
           svn+ssh://[email protected]/repos/main/Zope/branches/yourbranch
```
where rev3 is rev2+1 and rev4 is revision output by update.

As before, we look for and resolve conflicts, test and use svn commit to commit the changes to the trunk, making sure to include the merge information in the commit log!
What if I need updates that have been made in the trunk for the branch that I'm working in?
Stop and ask yourself why the branch is taking so long. :)

Branches should not last long enough for this to matter.

Reread: http://svnbook.red-bean.com/svnbook/ch04.html . Twice. No, three times. ;) Then use svn merge to merge the changes you need. If you ever merge that branch into the trunk, you will need to be careful to exclude the changes you merged.

You really don't want to do this.
Is there a way I can see the differences between two branches?
Yes - the svn diff command is your friend. To see all of the changes between the trunk and a given branch (for example brian-foo-branch):
```
      svn diff svn://svn.zope.org/repos/main/Zope/trunk \
               svn://svn.zope.org/repos/main/Zope/branches/brian-foo
```
This will give you a bunch of diff output showing you the changes in the trunk vs. the branch brian-foo.

Note that we didn't need to use a sandbox to get the diff. We could get the diff directly from the server. Also, we used an svn URL. We could as easily used an svn+ssh URL, but we didn't need to since we aren't writing any data.
Walk me through a quick example?
Ok - we're going to fix a bug. The problem is a simple typo in a docstring. We're going to make a branch since we want the fix in both the current release branch (Zope-2.8-branch) and the trunk.

We'll start by creating a branch:
```
       svn copy svn+ssh://[email protected]/repos/main/Zope/trunk \
                svn+ssh://[email protected]/repos/main/Zope/branches/brian-fix_typo
```
The svn copy command outputs the new revision number, which we note. Let's call this rev1.

Then we'll check out the branch into a working copy:
```
       svn co svn+ssh://[email protected]/repos/main/Zope/branches/brian-fix_typo
```
This creates a brian-fix_typo directory that we can work in. We edit the appropriate file to fix the typo, test the change and commit it:
```
      svn commit TheFile.py
```
Again, svn outputs the new revision number, which we note. Let's call this rev2.

Now we're ready to merge. We've made sure it's ok to merge into both the trunk and the 2.8 branch. Now we'll need a trunk sandbox to merge into:
```
       svn co svn+ssh://[email protected]/repos/main/Zope/trunk Zope
```
Now we can do the merge:
```
       cd Zope

       svn merge -r rev1:rev2 \
           svn+ssh://[email protected]/repos/main/Zope/branches/brian-fix_typo
```
Where rev1 and rev2 were the revision numbers output by the earlier svn copy and svn merge commands. Because this branch was so small and short-lived, we just noted the revision numbers as we went along. If we had failed to do this, or if there were many more modifications, we could use svn log instead:
```
      svn log --stop-on-copy \
          svn://svn.zope.org/repos/main/Zope/branches/brian-fix_typo
```
This command shows us all the changes made on the branch. We can use the range of revision number reported in our merge command.

Now we look for any conflicts and reconcile them if needed. We also run the automated tests to make sure we didn't break anything. When that's done, we'll commit, making sure to include the merge information in the log!:
```
      svn commit -m 'Merged Zope/branches/brian-fix_typo rev1:rev2'
      cd ..
```
Now we need to get a 2.8 sandbox and do the same:
```
      svn co svn+ssh://[email protected]/repos/main/Zope/branches/Zope-2.8

      cd Zope2.8
      svn merge -r rev1:rev2 \
           svn+ssh://[email protected]/repos/main/Zope/branches/brian-fix_typo

      # resolve conflicts and test, then

      svn commit -m 'Merged Zope/branches/brian-fix_typo rev1:rev2'
      cd ..
```
Finally, delete your branch:
```
      svn rm svn+ssh://[email protected]/repos/main/Zope/branches/brian-fix_typo
```
Do I need to update the changelog (doc/CHANGES.txt) as well?
Yes, but please be sure to modify it on the correct branch! The policy for updating doc/CHANGES.txt is described in ZopeDevelopmentProcess, and may be summarized as:
- You should note new features in CHANGES.txt on the trunk and not on any release branches.
- You should note bug fixes (with a collector number) in CHANGES.txt on the release branch to which you merged the change.
The release manager will take care of merging CHANGES.txt from the trunk and the release branch(es) as appropriate.
Should I ever delete a branch?
Yes. Unlike CVS, there is no need in SVN to keep old branches around. It's advisable to clean up your finished branches so other people don't have to guess which branches are still active. You can remove a branch like so:
```
      svn rm svn+ssh://[email protected]/repos/main/Zope/branches/mybranch
```
If you ever need the branch again, it can still be checked out and, if necessary, resurrected. See the Branching and Merging chapter of the SVN book for more details.
You said Zope 3 develops on the trunk--so, never make branches in Zope 3?
Of course not: branches are great tools for working on larger changes or for sharing work. However, the Zope 3 pattern encourages small, incremental checkins on the trunk in preference to branching for huge, cross-cutting changes.

If you're working on a change in one part of the code base and discover that it will depend on a change elsewhere, check out another instance. Change the dependency first and check it in with tests and documentation. Then move back to your original task, updating your original sandbox to get the dependency.