We usually provide a Migration Guide which is documentation on the wiki (Migration Guides) that consists of information regarding renaming operations, protocol changes, and any changes in the system of language changes that could affect the customization. It is also the link to check when you need to find information about new features.
Tips & Tricks
1. Break down Your Compilation Errors
After you set your base to the new version and try to compile your Extension, it is likely that you will face compilation errors which can be quite daunting. A good tip to categorize those errors is to divide them based on your Extension’s sub-directories. You can compile each subdirectory one by one using
compileAllBelow()method and C-M-space to trigger to run.
// Make sure you set the url to your sub-directory cm.runtime.util.compileAllBelow(cm.io.cmNative("custom/test/"), reportUnused=false);
2. Compare Your Old Source to Your New Target Branch
When you face a compilation error that you cannot solve easily, you may need to investigate that specific code block. In CET Operator, you can have both old and new version branches and open both on Emacs. Then you can trace and compare the code block and analyze the code's evolution. You can even do a stack trace, by calling
ssd() to see the list of methods that gets called previously to see if there have been changes made.
You can also use Git to your advantage by viewing the history of changes. If you are looking for more detailed information on a specific line of code, you can do a Git blame to check the modified time, author, and commit hash.
4. Create a Unit Test
If, for example, there is a specific method changed in core that is heavily used in your Extension and you are afraid it might have broken something, you can create a simple unit test that calls that specific method. But for some bugs, you might not be able to find it until QA tests your Extension.
You can do a unit test by using a
minitest syntax to test your function. You can write a test script in your function and make sure it will return the correct result. Make sure to add
cm.test package for your test function to work properly.
You can perform a unit test by creating a new file (i.e test.cm) and create your own test function. (Just make sure not to push your unit test to git!)
Best Way to Seek Help
After doing your own investigation and if you still cannot figure out the issue, the best way to seek help is to try to contact the developers that were involved in the change. You can also send an e-mail to Developer Support firstname.lastname@example.org. We also have a dedicated post related to the release in the CET Developer Forum on MyConfigura which would a great place to share your questions or concerns.
You can comment on these posts like 11.5 Release Question and Comments to seek help.
QA Migration Guide
QA Migration Guide is provided for QA to help them test the changes that have been made in Core. Compared to the original Migration Guide, the QA Migration Guide has a more detailed description of the new or changed feature with less code! It also pinpoints the features that may have an effect on the Extension so the QA will know what and how to test the features efficiently. It is also a helpful document for developers if they want a visual representation of the changes in Core.
Under the Migration Testing Guides, there is a guide for a minor release. This is a guide for QA if they are planning to do a migration for minor releases which is an optional process given to partners.