Several days ago, Mirth Connect version 3.3.0 was released. Noting the great new features, we decided to upgrade immediately (just days after the initial release). We followed these Upgrade Guide instructions during the upgrade. However, the specifics of upgrading from 3.2 to 3.3 are missing from these Upgrade Guide, so we did not suspect much to change on the way Mirth should be implemented...
During this process, we ran into a handful of issues that caused our production channels to go down for several hours (†).
It would have been really nice to have specific information for this upgrade. Some issues that would have been really useful to know beforehand (just examples, no need to actually answer):
Are you changing the default toString() method for objects/arrays to return JSON representations?
Does this upgrade include a db migration, meaning we can't revert to
previous version once upgraded?
Because code templates are now children of "libraries", will we need to access the code template through the library, or will we be able to call it directly (as it was in 3.2)?
A solid documentation like this would have allowed us to understand the full gravity of what needs to be accounted for when upgrading. Typically, Mirth has some documentation for each minor release. But even then, the documentation is very terse. Would it be possible for the Mirth team to start being very explicit with what the upgrade entails?
The Rails Upgrade Guide (obviously much larger team, so can spend more bandwidth on this spec) provides a really great example of what an upgrade guide should entail.
† yes, yes, I learned my lesson, I won't upgrade immediately to production anymore
The Release Notes page will give the lowest level of changes to the application, but you're right in that a better documentation is needed.
Related
Which is the more feasible strategy for version upgrades when you are multiple versions behind. For example from 6.4 to 2005.
Should we really do a version by version approach as SAP suggests. I understand it's recommended way but still.
Any one can share their experience regarding this?
What difficulties could be faced when directly migrating multiple versions?
Thanks!
There are several approaches you can take. Which one you take depends on the knowledge your team has and with the amount of customizations you already performed.
Step by Step
This is the recommended way by SAP. This is a more secure strategy, where it's very clear what changed between different versions. With every version, you will experience build failures, startup failures and possibly even data issues that need to be migrated. But it's very clear what version caused those issues. With the SAP help and the upgrade notes, you should be able to easily find what was changed, and how to fix it. Disadvantage with this approach is that you need to download, unzip and build for every version, and that takes time. Sometimes you even need to fix the same code twice, when the implentation was changed multiple times
One Shot
With this approach, you go straight to the latest version. You just put your custom code in the latest version and just see what build failures you get.
With this approach, it will be harder to figure out what exact version upgrade caused a specific issue. You should still check all upgrade notes, to make sure that no migrations are needed. Advantage is that you only perform everything once. If you have an experienced team, this is a feasable approach. If you have a new team, be carefull with this approach. You might encounter some difficult errors where you won't be sure what version caused them, so finding info in the SAP help might be harder
Hybrid approach
A third option would be a hybrid approach, where you upgrade several versions at once (For example to versions that contain big changes, like with the addition of backoffice in 6.3). This makes it easier to apply changes for those big changes, while you don't have to go through every version one by one.
Conclusion
I've tried all approaches in the past. The step by step approach takes a lot of time, but makes the changes easier and clearer. With the One Shot approach, you only need to download the latest version, but it might be somewhat harder to find the bugs. If you have an experienced team, you should go for the one shot approach. When you are a lot of versions behind and there were big changes, you could go for the hybrid approach
I had a similar requirement of upgrading from version 6.2 to 2005, I went with the One-Shot approach as explained by Yoni, and the biggest challenge I faced was due to Java version change.
I believe One-Shot approach and Step by Step approach will take a similar amount of time in the major version upgrade, though Step by Step approach is safe but redundant. My personal favorite is One-Shot.
I recently did a platform upgrade from hybris 6.7 to 2005 and did it step by step, mainly because of the java version change and, other than that, there were certain migration steps in each intermediate version that were needed to be done. Also the customer had a lot of custom promotion rules and they needed some special care.
In my case, the process in each step was this:
Upgrade to new version - there is an help.sap.com page for each step, I recommend you follow it and go through each of the section to see what applies to your project, e.g Upgrading Platform from 6.7 to 1808
Compile the project - some deprecated things will be removed in some steps and you have to refactor where needed. This step took me the most amount of time
Start the hybris server - after you finish the refactoring and your project builds successfully with ant clean all there is the possibility that the platform will fail to start due to some (now) incorrect xml config. The "good" part here is that you can see in the console what the problem is and the fix should go faster than the previous step.
Perform the necessary upgrade steps - here is the tricky part, once your platform starts you have to perform the necessary upgrade steps for each extension and add-on that needs it, otherwise you risk working with some broken business logic. You need to do some regression tests and check that everything works as it should.
All in all, an upgrade takes time and depends on how many versions you have to go through, but I think taking it step by step is the most efficient way to accomplish it.
I'm trying to figure out a scenario, but I can't find any relevant information on the web.
Let's say I am deploying an Android Application (v1.0.0) with the backend (v1.0.0).
At some point, I will make some changes and update the app to v1.0.1 and the backend to v1.0.1 and they will work perfectly.
But how can I also support the previous version of the application (maybe the new server version provides another format of response for one specific request)?
I thought of having separate deployments for every version of the server, but for many updates, that would mean a big resources impact.
Also, forcing the users to update doesn't seem a good option in my opinion.
Essentially you can go multiple ways of doing it. Really depends on your requirements, but usually the reality is a mixture of the things below.
As a rule of thumb, think in data model that will be held compatible. If the contract can not be kept or your realize major changes are needed, introduce a new version of API. If old clients can not be supported, force update. You can also agree on a policy on how long to support each previous versions and then force update, this will make your life much easier and simpler, than maintaining tens of versions of APIs.
Backwards compatible data model
You must think backwards with each release:
Think of incremental modelling with each release cycle. So you can keep things.
When you forget about it and you need to switch behavior based on data:
Happened to me in my trainee years. Simply you have to decode which version it might be, based on the data if you forget to add protocol version. From the beginning you can always have a version field on the data. Moreover, you can also add a set of compatible parser versions.
Include protocol version in data:
{
"data": [ arbitrary data model],
"protocolVersion": "v1"
}
Based on the protocol version, you can decide how to process the data on the server side. You don't need to keep client version in mind, only the protocol's. Since it can be that you release: 1.0.0, 1.0.1, 1.1.0, and you only change protocol in 1.2.0.
But I think the problem is the that as data changes subsequently, so does behavior on server side processing.
Versioned API
Sometimes you see different paths for major versions:
/api/v1/query
/api/v2/query
Used when backwards compatibility is broken or after total reconsideration. Therefore not every version will have an increment.
Use a query parameter with the client version:
/api/query?v=1.0
/api/query?v=1.1
Similar to previous one, just written differently. Although I think this is not the way you want to go down.
Track client releases and used service versions
In reality there are multiple requests and multiple versions of services being used all times per one client version. This makes things even harder to maintain.
All the time, document and track. Version and release management is very important. Know the git hash from which version you built, many time it can get confusing and you just changed only one parameter after release as a quick fix and the day after nothing is compatible anymore.
Map all service versions to the client version at each release, know which commit you really built and use tagging and release management.
Test everything before each release
Have clear requirements for your backwards compatibility. Maybe you only support two older versions, then test with all the two clients, new client with the to be released server. Document everything. And when you meet your criteria for release, go with it.
Summary
Reality is a mixture of solutions. Have clear requirements on the backward compatibility. Therefore you can test before each release. When it is necessary, force update. Keep track of releases, and document each client versions with all the services being used with their versions.
Use switch case at the server for each different version of the app.
Our frontend was built using Material-UI 0.18.7, and we realize that this is now very out of date. Our frontend guy is telling me that it would be nearly a total rewrite to upgrade to a 3.x release (and our frontend is large and complex) and we just aren't able to undertake that at this time. Beyond the obvious problems that come with a very old version, are there any special issues that would be caused by not upgrading?
Well since this is a front-end library, there is not much issues concerning security - which would be one of the main reason to upgrade.
You can see their changelog and search for keywords like 'security', 'patch' or w/e.
Of course the big reason to upgrade would be to get new features, more optimized solutions (if you are experiencing slow downs), bug fixes and much more.
Depending on the size of your front-end, it might be worth checking how much time it would actually take to upgrade.
Don't forget to take in consideration the time your front-end guy would need to implement new requested features which are already implemented on new versions, him needing to make dirty hacks to go through some known bugs, use other old libraries, etc... if you keep the old version.
My current live app is 1.2.3.
Internally i have released up to 1.2.3.5 for testing. I now need to do an emergency fix on the production app. this version should ideally be 1.2.4 , but it would be confusing, as it should have all changes upto 1.2.3.5 and it would not.
I cant make the new production app 1.2.3.1 because that was already released internally.
what should be the new version number for my app?
I would recommend something akin to 1.2.3 Update 1. Or, 1.2.3.0.1, although I personally think more than four version numbers is ugly and would go with the former. FWIW, Java also uses similar wording.
The other logical options collide with existing versions and have a good probability of causing confusion, as you have already pointed out.
Ideally I would begun using 1.2.4.x internally as soon as 1.2.3 was released, thereby reserving the rest of 1.2.3.x for out-of-band updates to the current production version. You may wish to adopt something like this for the future to avoid similar collisions, but it is truly personal preference.
I'm beginning development on a solution that will plug into an existing application. It will be made available for public use.
I have the option of using a newer technology that promotes better architecture, flexibility, speed, etc... or sticking with existing technology that is tried and tested which the application already uses.
The downside of going with the newer technology is that a major change to an essential config file needs to be made to support it. If the change goes wrong the app would be out of service. Uninstall is also an issue as future custom code by other developers may require the newer tech and there's no way this can be determined.
How important is this issue in considering an approach?
Will significant config changes put users off deploying code, or cause problems for them later?
Edit:
Intentionally not going into specifics about technologies here to avoid the question from being siderailed.
Install/uninstall software can be provided but there is some complexity involved which may cause them to foul up on edge cases resulting in a dead app. (A backup of the original config would be a way to mitigate that.) Also see the issue about uninstall above where I essentially can't provide one.
Yes, in my experience, any large amount of work will make users think twice about deploying or upgrading.
It's your standard cost/benefit analysis done by businesses with just about every decision. Will the expected benefits more than outweigh the potential costs?
When we release updates to our software, there's almost always a major component that's there just to assist the users to migrate.
An example (modified enough to protect the guilty): we have a product which generates reports on system performance and other things. But the reports aren't that pretty and the software for viewing them is tied to a specific platform.
We've leveraged BIRT to give us intranet-based reporting that looks much nicer and only needs the client to have a web browser (not some fat client).
Very few customers made the switch until we provided a toolset that would take their standard reports and turn them into BIRT reports. Once we supplied that, customers started taking it seriously - the benefit hadn't changed, but the cost had gone right down.
You've given us no detail, so we can't answer with any specificity. But if your question is, will a significant portion of your potential userbase be deterred from using your product if they have to do significant setup work, then the answer is yes. I've seen this time and time again, with my own products and those that I've installed myself. When the only config change is an uninstall and reinstall. People don't like to do work.
You may want to devote more effort than you've considered so far to making the upgrade painless. Even if you're upgrading someone else's framework, you may find the effort worthwhile and reflected in an increased number of installs.
I have noticed that "power users" - developers, sysadmins, etc. - are willing to put up with more setup work.
I'm not sure what you mean by "major config change", but if you're talking about settings / configuration files, then I've been doing something like this:
An application always contains a default configuration which is useful for most users, and which can't be replaced. Instead, users can override one or more of the default settings in their own, separate configuration file. When a new (major) version is released, most users don't need to reconfigure anything: their own custom configurations are still taken from their own configuration file, and possibly required new parameters are taken from the new release's default settings.
It's obvious that most users don't want waste their time adjusting some settings that already were right - and quite rightfully so.