Our backwards compatibility policy for Apostrophe 3.x admin UI code

[boutell]

We'd like to share this policy with the community here as well as adding it to our website so folks know what to expect if they customize the admin UI code with custom components.

The following policy applies to backwards compatibility of custom Apostrophe admin UI code during the Apostrophe 3.x series. If your project does not contain custom Vue admin UI code that contributes to Apostrophe's admin UI build (ui/apos subdirectories in your own modules), you need not be concerned with it. Some of these policies differ from the semantic versioning standard, which is otherwise observed in Apostrophe 3.x releases wherever security permits.

Because Vue 2 has a limited lifespan and Vue 3 has always been planned for Apostrophe's admin UI, migration to Vue 3 will occur at some point during the Apostrophe 3.x release series. This should not impact your project-level use of either version of Vue for non-admin UI purposes.

A clear announcement will be made in advance of release of any upcoming migration from Vue 2 to Vue 3.

Any migration from Vue 2 to Vue 3 will be carried out in a minor version change, not just a patchlevel change.

We may make necessary BC breaks to migrate the admin UI from Vue 2 to Vue 3, including those that may impact your custom admin UI components. However we will keep these as small as possible.

If we have provided a well-known way to configure a custom component for a particular purpose, such as an input field component or a column header component, we will take particular care to avoid bc breaks where possible.

More complex "manager" components, such as AposDocsManager, may undergo somewhat more rapid evolution. Bear in mind that if you override them you take responsibility for staying up to date with changes in the API of the original version.

After the migration to Vue 3 we will pursue a more strictly backwards compatible policy for any further changes that could impact custom admin UI components.