Forum OpenACS Development: Summary of Package development with CVS

Collapse
1: Summary of Package development with CVS
Posted by Jade Rubick on 07/01/04 02:13 AM
This is my understanding of how package developers are supposed to be using CVS right now.
  • Package developers are supposed to essentially ignore the oacs-5-1 and oacs-5-2 etc branches, unless they're dealing with core packages. These branches are just for core. The reason for this is we've separated release of core and packages.

  • Package bug fixes go to HEAD.

  • New features can be worked on in separate branches and merged back into HEAD. These branches can be called whatever the heck you like, as long as it doesn't conflict with other branch names.

  • Whenever you would like to make a release of a package, you use the APM to bump a version number, commit your work, and TAG it with a tag such as openacs-5-1-compat. So your work isn't released to the public until you tag it.
    tag -F openacs-5-1-compat

  • The package repository builds the project repository based on the compat tags.
Collapse
2: Re: Summary of Package development with CVS (response to 1)
Posted by Jeff Davis on 07/01/04 08:07 AM
Jade, this was covered in tip 61.

It's definitely not the case that package developers should ignore the release branch; in fact generally speaking unless you are developing a package which requires features only present on HEAD developing on the current release branch (oacs-5-1 now) is probably better. Also, bug fixes absolutely should go into the release branch if the release branch is affected by the bug (though it's fine to apply it on HEAD and merge it to oacs-5-1 or vice versa).

Release branches are feature frozen only for core, so for packages working on the release branch is not a constraint. It also means that it will be easier for people to verify the package actually does work on the release branch.

I am leary of creating lots of branches for package work (and don't think it's necessary unless you are going to break something for an extended period); branching is the prefered alternative to what we had been doing (which was putting branched versions of packages in contrib). I personally would like these package branches to be named in some way thats consistent (and when someone really does need to do it we should discuss it -- they should post or ping OCT first I think).

Collapse
3: Re: Summary of Package development with CVS (response to 2)
Posted by Jade Rubick on 07/01/04 07:11 PM
I guess what I'm looking for is guidance for what was left out of tip 61.

I've been told by more senior developers to commit packages to either HEAD or the oacs-5-1 branch. Different people tend to say different things.

The installation docs have people checkout packages using the compat tags. That makes development on either HEAD or the oacs-5-1 branch possible. So I guess either approach is acceptible, and that was why it was left out of TIP 61?

Other developers have expressed confusion. They would like some direction as to how to checkout packages and help contribute to them. Having two different systems makes it more complicated for them to get involved. People are asking me which branch they should check out, and I'm not really sure what to tell them. We don't really have a standard way of doing it.

Currently, I do my development on an OpenACS 5.1 installation (my developmental server). Once it is tested, I make a patch of my work, and patch the package in a checkout from HEAD, commit, and tag with openacs-5-1 compat. This allows me to make local edits in separate commits, but it does add some complexity. And it's not the most robust way of doing things.

I've asked in the past about the best way to set up CVS for development and production, to have local modifications, and still interact with OpenACS. The consensus seemed to be that CVS is not very good for this, and that everybody does it their own way, and no way is perfect, and darn wouldn't it be nice if we were all using Arch. I'd personally prefer to hear of one way that less experienced developers can default to while we learn the ropes, even if it's not perfect.

I'd like to write the documentation for this, so it's up there for everyone. But I'm still not totally clear on what the preferred way to do things is.

Collapse
4: Re: Summary of Package development with CVS (response to 3)
Posted by Jeff Davis on 07/01/04 08:32 PM
Here is my view on developing versus CVS:
  • Doing development is easiest if you check out on a single branch.
  • It's bad to check out on a symbolic tag (which is what -compat is) to do development since it will be "sticky" and you will not be able to commit.
  • HEAD breaks -- it's less stable than the release branch and for most people not working on features in acs-core it's not the best alternative.
  • Sometimes people need to use features only on HEAD in which case developing on HEAD is the only choice.
In very general terms: develop on a checkout of oacs-5-1 (checked out with "cvs co -r oacs-5-1") unless you are adding features to acs-core or need to use features added to acs-core which are only on HEAD.

As for developing in your own CVS repository and merging back, there is a lot more complexity and I don't think if you are less experienced with CVS that there is going to be any easy solution. I think for most people the best bet is either stick to submitting patches versus the reference copy you got or working on an openacs.org CVS checkout making parallel changes to whatever you are doing in your production environment (i.e. exactly what you are doing now).

Or, yeah, find someone to act as gatekeeper/patch merger between CVS and an Arch repository and switch to Arch.

Collapse
5: Re: Summary of Package development with CVS (response to 1)
Posted by Mark Aufflick on 07/02/04 05:32 PM
I second Jeff's explanation of branches being far more suitable to our release needs than tags. Another issue will be how to deal with bug fixes for oacs-*-compat. Do you just bump the tag with cvs tag -F ? That is imho a bad idea because you retain no history. It is also a real pain the further you get from the release since a bug fix won't be as simple as re-tagging the current HEAD file (it may have diverged).

Joel's comments in this thread seem to indicate that the packages will be part of the version branch, so what are the -compat tags for?

Collapse
6: Re: Summary of Package development with CVS (response to 5)
Posted by Jade Rubick on 07/03/04 01:21 AM
I'm not sure about the compat tag. I'm curious to hear Joel's thinking about this. Currently, however, it IS important to use the -compat tags, because they set up what the package repository creates, I believe. So if you don't tag it, it's not available to many people. And I do update the tag (tag -F openacs-5-1-compat inside the project-manager directory).

For project-manager, I've copied all my HEAD changes to the oacs-5-1 branch as well.

I'll be doing all development on the release branches (currently oacs-5-1), and tagging with openacs-5-1-compat whenever things seem ready for release.

Collapse
7: Re: Summary of Package development with CVS (response to 6)
Posted by Joel Aufrecht on 07/03/04 07:43 PM
Jade: "I guess what I'm looking for is guidance for what was left out of tip 61."

Consider this an RFC for changes to TIP 61.

  • Rule 1.1 ("For non-core packages, developers should use their own judgment on when to deviate from the basic approach.") should be changed to
    Developers should work on a checkout of the release branch of the lastest release. For example, if OpenACS 5.1.0 is released, developers should work on the oacs-5-1 branch. When oacs-5-2 is branched, developers should continue working on oacs-5-1 until OpenACS 5.2.0 is actually released.

    Reasons: First, this ensures that developers are working against stable core code. Second, it ensures that new package releases are available to OpenACS users immediately.

  • Rule 3.3 will be clarified with a link to Naming Database Upgrade Scripts
  • New rule: Rule 5. When a package is released in final form, the developer shall tag it "packagename-x-y-z-final" and "oacs-x-y-compat". x-y should correspond to the current branch. If the package is compatible with several different core versions, several compat tags should be applied.

    Reason 1: The packagename tag is a permanent, static tag that allows for future comparison. The compat tag is a floating tag which is used by the repository generator to determine the most recent released version of each package for each core version. This allows package developers to publish their releases to all users of automatic upgrade without any intervention from the OpenACS release team.

    Reason 2: The compat tags allows CVS users to identify packages which have been released since the last core release.

    Reason 3: The compat tag or something similar is required to make Rule 6 possible.

  • New rule: Rule 6. When OpenACS core is released, the openacs-x-y-z-final tag shall be applied to all compat packages.

    Reason: This allows OpenACS developers who are creating extensively customized sites to branch from a tag which is stable, corresponds to released code instead of development code, and applies to all packages. This tag can be used to fork packages as needed, and provides a common ancestor between the fork and the OpenACS code so that patches can be generated.

Collapse
8: Re: Summary of Package development with CVS (response to 7)
Posted by Jade Rubick on 07/07/04 07:17 PM
Joel: that was exactly what I was looking for. It all makes sense to me.
Collapse
9: Re: Summary of Package development with CVS (response to 1)
Posted by Jade Rubick on 07/15/04 06:26 PM
Well, since nobody has commented on the RFC, Joel, would you mind TIPping this?
Collapse
10: Re: Summary of Package development with CVS (response to 9)
Posted by Mark Aufflick on 07/17/04 04:23 PM
Looks good to me.