Log in
Forgot your password?
History for ZopeCVSFAQ
??changed:- 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 CVS. Many of the items apply to other areas in the Zope repository, in addition to the Zope area. o **I know nothing about CVS. How do I start?** A good place to start would be the "Introduction to CVS":http://www.cvshome.org/docs/blandy.html . There is also an online verion of "Open Source Development with CVS":http://cvsbook.red-bean.com/cvsbook.html that provides good background information. Another handy thing for CVS users is the "CVS Quick Reference":http://www.cvshome.org/docs/ref.html . See CVSResources for more leads. o **How do I check out Zope?** Most people have read-only access - see ReadOnlyAccess for instructions. The quick hint, if you've done checkouts from this host before, is:: cvs -d :pserver:[email protected]:/cvs-repository co Zope For those with write privileges, see WriteAccess. The quick hint, if you've got all the incidentals in place (and replacing 'MyUserName' with your zope.org account name):: cvs -d :ext:[email protected]:/cvs-repository co Zope o **What do you mean by "the trunk"?** The trunk is the main line of development in CVS 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 is done on *branches* in CVS 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. o **So does that mean I shouldn't check things directly into the trunk?** Right - 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 <a href="http://www.enteract.com/~bradapp/acme/branching/branch-creation.html#BranchPerTask">Streamed Lines</a>. o **Ok, so when am I supposed to make a branch?** 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. o **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. o **Can I work on both bug-fixes and features in the same activity branch?** It is almost always best to separate 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. o **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.2 goes into beta a branch named 'Zope-2_2-branch' is created and subsequent releases in the 2.2 line are created from the 'Zope-2_2-branch' branch. You can usually do a 'cvs log' on a file in your sandbox and see the highest 'Zope-x_x-branch' tag listed to figure out the current release branch. If you are not sure, ask someone! o **So how do I make a branch for my work?** To create a sandbox on an activity branch, first check out a normal (trunk) sandbox and cd into it. Next, we will tell CVS that we want to create a branch rooted at the version of the trunk we've just checked out. To do that, use:: cvs tag -b my_project-branch This will create the branch in CVS called 'my_project-branch'. Note that the previous command will not automatically update the current sandbox to be *on* that branch. To do that, use:: cvs update -r my_project-branch That will put your current sandbox on that branch. o **How should I name branches I create?** The convention that we want to use is that *your name*, a descriptive element and the suffix '-branch' be used in branch names. Ending branch names with '-branch' makes it easier to tell which CVS tags are branch tags, and 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-branch amos-new_help_system-branch jim-zclass_armegeddon-branch o **How do I check out a sandbox on an existing branch?** You can use the '-r' argument to CVS to check out a new sandbox on a given (pre-existing) branch. For example, this will check out a sandbox on the 'brian-dav_level2_support-branch' branch into the directory 'dav_work':: cvs co -d dav_work -r brian-dav_level2_support-branch Zope *Note that the '-d' option that comes after the cvs command (co in this case) is different than the '-d' you can give directly to 'cvs'. In this case, the '-d' option to 'checkout' says "checkout Zope on this branch, and name the resulting directory 'dav_work'". Specifying '-d' directly to 'cvs' tells cvs which repository should be used.* o **How do I do my work on the branch?** You work in your branch in the same way you would work in any CVS sandbox. You make your changes and use 'cvs 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. o **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. CVS 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*. [186 more lines...]