Development Guidelines

by vangheemn — last modified Mar 18, 2010 10:34 AM

— filed under: Subversion, documentaton, code, repository

some basic guidelines in developing Plone products at UW Oshkosh.

Just some good information on working with Plone on campus here. Please check out each link, especially the related links, and ask questions if things don't make sense.

Naming Conventions

Products

All products should be named starting with the "uwosh" namespace and preceding with a description 2nd level namespace. If the product is simply for portlets, it might work to prefix it with "uwosh.portlet."

CODE

indent with 4 spaces
class names use camel case(ClassName)
function and variable names can use c++ style(my_variable)
All classes should use implements(IClassName) where appropriate

Versioning

The version of the product goes into the "version.txt" of the product. This version should match the version in the "setup.py" file. The version DOES NOT go into the "metadata.xml" in the profiles directory of the product. This is a common mistake that many Plone developers are recovering from and fixing.

The version in the "metadata.xml" file is specifically for the version of the generic setup profile since it is highly possible to have a different version of the GS profile than that of the product. It is advised to simply use sequential numbers for this only. You shouldn't experience any adverse affects in changing to the sequential number practice.

Please read version numbers in quickinstaller to understand better the history and reasoning behind this.

Managing Upgrades

For any changes in a product, provide upgrade steps to handle the migration. Do not use the "Extensions" folder "Install.py" install and uninstall methods anymore. This is depreciated and a very ugly way to handle upgrades.

You must provide an upgrade step for any changes to the GS profile. DO NOT rely of the "reinstall" of products to upgrade the GS profiles. This is considered improper and potentially dangerous to re-apply GS profiles constantly. Ideally, we never run the "reinstall" method of a product. If you've changed something in the GS profile, you do not have to re-apply all of your GS profile in the upgrade step, you can run only certain parts of your profile if needed. For an example of how to specify certain parts of a GS profile to run, take a look here.

If you provide upgrade steps for every version of your software, you'll allow users to easily migrated multiple versions at a time if they need to. Also, in Plone 3.3.*, the upgrade steps are automatically ran when clicking "upgrade" in the add/remove products section of site setup. In older versions you'll have to manually run the upgrade steps in portal_setup.

For an example of how to use upgrade steps in Plone products, take a look at uwosh.flash.

Documenting

Documentation in your code isn't a huge deal as long as things make sense, just note things that are out of the ordinary.

Some basic information in the README.txt file is *required*.

After the initial release, please put information in the HISTORY.txt file so people know what has been changed/added/fixed from version to version.

Sometimes browser tests can help to document. If it is a complicated system for users to understand, sphinx documentation might be better used.

Testing

You don't need to go overboard with testing. We're not looking for 100% coverage or anything like that. Most of the things we use are not libraries or tools and a lot of it is just template code it gets to the point were it can be pointless to add tests for it. Since Plone is a development package in itself, all the things we use in our Products are themselves tested well.

However, if there is a lot of custom behavior and complex interactions, you must test it. Browser tests(integration testing) are preferable as unit test can be cumbersome with Plone and aren't always broad enough. Please use your best judgement in how much testing is useful to ensuring the quality of the code. There is a point where too much testing just lowers productivity, wastes time and adds little to the flexibility and quality of your code.

SVN

Our SVN isn't very busy so you can pretty much use it however you want. Tagging isn't a huge deal as you can always get specific revisions anyways and they just waste space.

If you're doing a major overhaul of the product, do a branch and then merge back in with the trunk once your done. I've found these zope guidelines very useful in working with SVN.