It is important to know which version of your product is installed. This especially helps with bug reports. Is someone using 1.0 from your tar ball? A bug fix release from a branch? The cutting edge version from trunk? Read on for some advice on version strings and source code control with subversion.

Version strings

You have just finished ShinyNewProduct and think it is ready to take the market by storm. Great! Let's release it then. Of course you have developed your product in a source code control system. The favourite among Plone developers seems to be subversion, or svn for short. This tutorial will focus on that, but the concepts should be applicable to CVS (Concurrent Versioning System) or other systems. For tips on using CVS instead of subversion, see this tutorial.

Plone versions 3.0, 3.1 and 3.2 incorrectly used the GenericSetup profile version as specified in metadata.xml as package version. This was corrected in Plone 3.3. In Plone 3.3, for eggified packages, the version from the setup.py file of the egg is taken. If the product is not eggified, or the version variable from the egg could not be found, the version.txt file is used instead.

You can argue a lot about the numbers that need to go in there, but your ShinyNewProduct feels like a 1.0 release, so let's just put that in the setup.py file:

version = '1.0'

and commit the change:

commit -m 'Prepare release 1.0'

You should choose a numbering sheme compatible with setuptools, as stated in this doc.

Branches, tags and trunk

Let's say you have your product in http://localhost/svn/ShinyNewProduct. Your actual code should be in a directory called trunk. If you don't have that, it is beyond the scope of this tutorial to help you change that. What I will do is show you how to add two more directories. If you already have them, great!

svn mkdir http://localhost/svn/ShinyNewProduct/branches
svn mkdir http://localhost/svn/ShinyNewProduct/tags

The main development is done on trunk. You could choose to develop only on branches instead. In fact, for big changes that take longer than a day to finish, this should be standard practice. It is easy to copy the trunk to a branch, develop code there, merge the changes back to trunk when you're happy and possibly remove the branch again.

Anyway, assume for now that your latest greatest code is in trunk. Now, when people start using your product, they will probably find bugs. That's okay, bugs thrive on software, so it's to be expected. There's no need to be ashamed of yourself. Just fix the bugs. But your users will not only find bugs, they will also come up with feature requests; and if not, then you yourself will. You made the decision to develop new features on trunk. But when you fix a bug your users want to be able to use version 1.0 plus the bug fix, without any new features which may be buggier still (or so they think). So then where do the bug fixes go?

Bugs will need to be fixed in your latest code and in the code that you just released as version 1.0. So at release time you copy your trunk to a branch:

svn copy http://localhost/svn/ShinyNewProduct/trunk \
http://localhost/svn/ShinyNewProduct/branches/1.0

When bugs surface you can fix them on that branch and merge the changes back to trunk.

Sometimes you want to be able to go back to the exact version of your product at release time. Your clever bug fix may have broken something so this branch is unusable at the moment. That's when the tags subdirectory comes into play. At release time you should do:

svn copy http://localhost/svn/ShinyNewProduct/branches/1.0 \
http://localhost/svn/ShinyNewProduct/tags/1.0

Whether you copy trunk to branches to tags or trunk to tags to branches shouldn't really matter, as long as you don't commit anything in the mean time. Note that committing changes to a tag is a violation of best practices. Anyone should be able to count on the fact that tags/1.0 really contains the code as it was when version 1.0 was released, without any bug fixes or other changes. There are ways to actually prevent committing to an existing tag, but that's beyond the scope of this tutorial.

Now is a good time to change the setup.py file in branches and trunk to signal the new state of the software. After the first release, the setup.py file should contain what follows:

 In tags/1.0:

version = 1.0

In branches/1.0:

version = 1.0dev

In trunk:

version = 1.1dev

After you commit changes to the branch or trunk you can increase the version in the setup.py file to signal the change. Note that we have given trunk a version number starting with 1.1. You do want to continue developing don't you?

Make a tar file for downloading

Now you can prepare a tar file that people can download from a website when they don't want to use subversion. Best is to make an export from the tag. An export instead of a checkout ensures that there are no subversion directories or old .pyc or backup files lying around. Double check to make sure the version number in version.txt is plainly 1.0.

svn export http://localhost/svn/ShinyNewProduct/tags/1.0 \
ShinyNewProduct tar czf ShinyNewProduct-1.0.tar.gz ShinyNewProduct

Okay, you now have a trunk, tags and branches with version numbers to match and you have a tar ball. You have taken a big step towards releasing your ShinyNewProduct. Actually, the most difficult part is finished now, so you can breathe and relax. Then again, you still need to tell your future users what your product does, where they can download it and how they can contact you to express their gratitude (or perhaps how to complain, but that's a corner case). Read on for more advice on that.

Plone Software Center

First of all, login to plone.org. What? You don't have an account there yet??? Quick, go subscribe immediately before someone notices. For the others: go on a coffee hunt; you deserve it!

Ah, that's better. Right, you are logged in. Now go to plone.org/products. You should be able to register a new product there by clicking the button marked ``Add new software project''. This will show you an edit form where you can add a new Plone Software Center. This comes with a tutorial that you really want to read as it has lots of tips that I fail to mention here.

Basically, here you can point to a home page, a contact address, a code repository, etcetera. Everything you always wanted. Add the information that is relevant for your project. Maybe add some documentation already or write some improvement proposals or add a bug tracker. Then submit your project for review and wait patiently for one of the reviewers to make your project public.

Place of your code repository

You can keep your subversion repository on a server that you yourself maintain. If your product is any good, you will sooner or later get patches from other developers. If they are really enthusiastic, they will even ask for commit access to your repository as they want to submit changes themselves, perhaps on a branch. That is certainly a workable solution, but you may want to spare yourself some hassle and follow the pack to the plone subversion repository. Probably the collective is the best spot. Follow the instructions for how to get write access to the plone collective svn repository.

Now what am I forgetting? Ah, remember that tar file you made earlier? Add a release to your product page and add the tar file there so people can download it. When you are ready publish the release and prepare for an onslaught of users. But wait! Don't do that yet. You may first want to setup some mailing lists so people can ask questions and search for answers. Read on.

User mailing list

Don't look here for advice on which mailing list software to use. You may want to use some ready made lists like on SourceForge. You can also decide to just point users to the general plone-users mailing list. That's fine. See plone.org/support.

But if someone has a problem with your product and mails the plone-users list with a subject line of just Problem you are likely to ignore that message. If he instead uses a mailing list specifically aimed at your product, you are much more likely to read his mail. Well, that's one reason to create a mailing list for users.

If your product is very successful and also draws attention from a lot of developers who want to embrace and extend your code, you could add a mailing list specifically for discussing development. But stick to one user list for now.

Issue mailing list

There is one other list that you may want to add: a list where bug reports are automatically sent. For example if you added a Poi issue tracker to your product page in an earlier step, you can choose to send any bug reports to a few email addresses or you could let them be sent to a mailing list. Anyone interested can subscribe to that list. This safe you some hassle.

Newsgroup via Gmane

When setting up the user list for my own eXtremeManagement product, some fellow developers told me they would like the list to be available as a newsgroup via gmane.org. That is fairly easy to setup, so I suggest you do that as well. Just follow their instructions. I'll add one remark: to make sure users can easily find the newsgroup, make sure you stick to the naming convention for plone lists. In this case I would suggest as a group name: gmane.comp.web.zope.plone.shinynewproduct.

After some time (could be several days) you normally get an email with a courtesy copy of an article that has been posted to the gmane.discuss.subscribe newsgroup as well. Follow any instructions that you read there, if any. Usually this will tell you that everything is ready and the newsgroup will automatically be created after the next email is sent to the mailing list.

Make sure you mention your new mailing lists and newsgroups on your products page in the Plone Software Center on plone.org. Okay, now you can start using the lists. How about announcing the first release of your product there? Read on.

Content of announcement

Please download my eXtremeManagement product. It is very good. Click here!!!

Did you just click that link? Yes? Then spammers must love you. No? Okay, then you agree that your announcement should be better than that. For starters, you want to provide more information, to entice your readers to follow that link. Your potential users will have some questions:

• What is the name of your product?
• Who is releasing this?  Is it a product just from you or does it have a company behind it?
  
• What does it do?
  
• What does it do differently than other similar products?
  
• Is it a Zope, CMF or Plone product?
  
• On which Zope and Plone versions has it been tested and known to work?
  
• What other products does it depend on?
  
• Where can I download it?
  
• Where can I get more info?

Don't overwhelm your readers though. Two screens full of information should be the limit. If you need more than that, provide some links instead. Just concentrate on clearly saying what your product does and throw in a link to more detailed information, like install instructions.

Where to send it

Are you done writing? Great! Have you done a spell check? Wonderful! Has it been proofread by co-workers or so? Even better! Now send it out. If you made a mailing list, send it there first. Then inform the plone community. Go to plone.org/support and find the address of the plone-users mailing list or newsgroup and post it there. Don't use the plone-announcement list: that is only for core Plone itself, not for Products. Are you often found at irc? Then throw a line or two in the #plone channel.

Now let the feeling sink in that you have really released a Plone product.  Congratulations.  Now throw a party and do the happy dance!