Best Practices for Customizing Your Live Plone Site

Plone is increasingly allowing you to build an entire site through the web (TTW). This is great for new Plone users or when you need to throw up a site quickly without dealing with the code. But if you are a Plone developer, I recommend keeping all your customizations in version control (like Subversion or Git), only doing TTW customizations sparingly.

For customizations, I am referring to making changes to templates, Python code, stylesheets or Javascript that may be in the Theming control panel, portal_skins, or portal_view_customizations.

Why should these customizations be avoided?

• When changes are made directly in the site, there is no information kept as to when or why that change was made. When changes are checked into version control, this information is stored in the commit, which can prevent many future headaches.
• If you make a mistake in the customization, it can break your site. This tends to be limited to a single page or template, but I've also had to clean up after a client that rendered their site completely useless after they had made a change to the colophon.
• With customizations, you're more likely to be in a hurry and not fully test the changes being made.
• Also keep in mind that with any Plone upgrade, you should update your customized templates if those templates had changes in the Plone core. This will especially be needed when upgrading to Plone 5, where many templates have been moved, and can no longer be customized using portal_skins. For me, managing these updates is much easier when working with the code.

How to make customizations properly

First decide if it's appropriate to do directly on prod - Think twice before applying some complex solution directly on your production instance. If it's a change that may need extensive testing, don't do it on prod.

Add comments - Add a comment with the line of code you are changes, so you can remember later why it was done.

Commit the change - When you do make a change on prod, apply the same change to your code so there is a record of the change, why it was done, and what ticket is it attached to. With this commit, you can also include an upgrade step that will remove the customized file next time the code is released.

Process is Important

Here is the general process we follow for fixing bugs or adding customizations to a site:

• Use a local checkout of the site, make the change, test and commit.
• Tag the code and release it to a testing instance.
• Test the code. If there's something wrong, it goes back to the developer. Repeat steps until your QA team say the code is good.
• Release the code to prod.

Was this article useful? Let us know in the comments below. For more, be sure to sign up for our Plone & Python How-To digests and receive how-to guides as soon as they are published!