Choosing the best versioning option when publishing a form

Orbeon Forms supports versioning of form definitions since Orbeon Forms 4.5 [1].
Since Orbeon Forms 4.6 [2], Form Builder also allows you to control whether a new form definition version must be created:

Creating a new version

Or whether the last existing form definition version must be overwritten:

Overwriting an existing version

You notice that there are warnings associated with each option! Ideally, we wouldn’t have a need for them, but the use of each option has different consequences on published forms.
So which option should you chose when you republish a new form definition?

1. If there is no data associated with the form definition in the database, it is safe to overwrite the latest form definition, unless you really want to keep the older version published.
2. If there is data associated with the form definition in the database and the changes you have made to the form definition
   1. are not structural, it is also safe to overwrite the latest form definition.
   2. are structural, it is not safe to overwrite and you should create a new version.

The following operations count as structural changes:

• adding controls, grids, or sections
• removing controls, grids, or sections
• moving controls, grids, or sections
• renaming controls, grids, or sections

The following operations are not structural:

• changing the form’s title or description
• changing a control’s label, hint, help, or alert message
• changing a section’s title or help
• adding or removing repeated grid or section iterations
• adding or removing languages
• changing the form’s permissions
• adding, changing, or removing the form’s PDF template [3]

In general, the following non-structural operations are safe, but can have consequences on data validation and access:

• adding or removing services and actions
• adding, changing, or removing validations or formulas
• adding, changing, or removing an XML Schema

For example if validation rules change, the situation can arise where data stored in the database was valid at the time it was saved, but the new form definition considers them invalid. So viewing the data will work, but attempting to save without changes will not satisfy the new validation rules and will fail. It is important to be aware of this when making validation rules changes.
Similarly, changing actions or visibility rules can make the form behave differently when editing or viewing existing data. Here again, you must be cautious.
Now you might ask, what is the drawback of always creating a new form version when publishing?
Existing data in the database is associated with a specific form definition version. This means that existing data cannot be viewed or edited with a different form definition version. So a fix for a typo in a control label, for example, wouldn’t show when editing or viewing existing data. This may or may not be acceptable depending on your use case.
As discussed in the original post about versioning, we hope to enable more scenarios with basic data migration in the future.

---

1. As of Orbeon Forms 4.8, versioning is supported with relational databases, but not with eXist. See also database support.  ↩
   
2. That’s a couple of versions ago, since as we write Orbeon Forms 4.8 has just been released, but we didn’t get to talk about this feature until now!  ↩
   
3. Note that changing the PDF template can cause incorrect PDF production for existing data if the PDF template is incorrectly setup.  ↩