Introduction

This guide will highlight some of the best practices that we recommend developers should follow before publishing an extension update.

Be Careful of Interface Changes

One factor to consider when publishing are interface changes. This could be interface changes introduced in either your own extension or maybe core if this is published alongside a CET major release. Interface changes tend to lead to compile errors and broken behaviors if it is not handled properly. As such, introducing interface changes can carry a huge risk and it is not recommended to introduce them unless it is for a major update. Also make sure to refer to migration guides to handle interface changes from core.

Examples

Removal

Removing a definition is considered an interface change.

Removed: public class GenRectRackSnapper extends GenRackSnapper;
Removed: extend public double adjustmentHeight();

If a definition is not needed anymore, consider deprecating it and add a MergeTODO to clearly state that it should be removed during the next major update.

/**
 * Adjust height to standard rack height.
 * MergeTODO: Remove in Nov update. Not used anymore. 
 * Kept to avoid interface change.
 */
extend public double adjustmentHeight() : deprecated {
    return 2.8m;
}

The reason it shouldn’t be outright removed is, it may still be referenced by another related extension or package. So, while the current package or extension will compile fine, there is a risk of breaking something elsewhere. If a definition is removed, all references to it should be confirmed before publishing an update. Do note that developers are also responsible of handling any issues from loading old drawings as a result of removing fields.

Changing method and function signature

Changing or adding parameters to an existing function/method is another example of an interface change as it changes their signature. It is quite common to add a new argument to an existing method to fix an issue.

Old: extend public str[] getOptionsKeys(str featureKey)
New: extend public str[] getOptionsKeys(str featureKey, Object env=null) 

One way to avoid an interface change in this scenario, is to overload the method instead of modifying the existing method and have the old method call the new one.

/**
 * MergeTODO: Remove during Nov update.
 */
extend public str[] getOptionsKeys(str featureKey) : deprecated {
    return getOptionsKeys(.., env=null);
}


extend public str[] getOptionsKeys(str featureKey, Object env=null) {
    ...
}

This way, there should be no change in behavior whenever the original method is called.

Avoid Compile Errors

Compile errors are sometimes missed due to our compiler being lazy. As in, the compiler only compiles code when it is needed instead of pre-compiling the entire code base. What this means is a seemingly harmless change could trigger a compile error in another package that wasn’t loaded resulting in the error going undetected by the compiler. To avoid this, all packages in the extension should be included when making a new build to ensure the builder catches these compile errors. It is also worth running compileAllBelow on the entire extension to detect all errors.

// Make sure you set the url to your sub-directory
cm.runtime.util.compileAllBelow(cm.io.cmNative("custom/test/"), reportUnused=false);

It is also possible to setup a Gitlab Runner to run against all merge requests to check for build errors before merging any new changes.

Use Custom Distributions

Before uploading a build to the official build box, it is recommended to create a custom distribution and upload it there. This distribution can be used to test the build before it goes live. This can be tested by the developers themselves or a small group of users/testers. It is a good way to catch installation and update errors.

Use Official Beta Boxes

Build center in my Configura has other official distributions besides “Official”. A “Beta” distribution is also available that is used to test an upcoming CET update.

A build can be added to the Beta distribution to ensure that it is compatible with an upcoming CET update.

Perform Smoke Tests

It is always recommended to perform smoke tests before publishing an update. These tests should be run in either the custom distribution or the official beta boxes before uploading the build to official.

Test After Publishing

If all the above was followed, then the update should be published with no issue. Any build and update errors should have been caught before it went live. Nevertheless, it is always good to try out the update yourself once it goes live. If any issue is found that wasn’t caught before, you will at least catch it early and have some time to address the situation before it impacts many more users.