How to review changes when there is a custom version

If a file for which a custom version has been created is updated, you get the message: “Upgrade process will update some files but these files also exist in custom/ folder. Please review the changes before continuing:”

How, in practical terms, are you supposed to be able to review the changes before installing the upgrade? Why is there not a set of detailed release notes that explains precisely what is changed in each file in a release package? I realize that you need to decide on a case by case basis whether your customizations are still applicable after the upgrade, but is there some more intelligent way of handling this issue, other than trial and error or, even worse, either wiping out your customizations or ignoring the changes in the new release?

Before running an upgrade you should always take a full back-up of your database and of your files.

You should also keep track of all your customisations so that you could easily re implement them in case something happens to your instance.

In any case I think that old files that are rewritten by an upgrade shold be saved in a folder called something like:


If you navigate these folders you should find your original files and, by comparing them with the new ones you should be able to restore the customisations.

That doesn’t answer the question about documentation of what, exactly, is changing in those updated files. Doesn’t it make more sense to document these details once, rather than obliging 100 000 users to try to figure that out on their own?

If you look at the release notes (each version has them) there is a list of all the things that ha been changed.

On the left of each line of the release notes there is a (clickable) number which corresponds to the gitHub PR (= Pull Request = code change) or Issue (which in turn refers to a corresponding PR, but you have to go to the PR to see the files changed tab). So if you click on a PR number you are redirected to gitHub where you can see all the changes (files + modified lines). Added lines of code are marked with a “+” (plus) sign and removed lines of code are marked with a “-” (minus) sign: you can dig to the extreme detail. You can choose to look just at the parts of code that have been modified (default) or the entire files.

If you are redirected to an Issue you just have to read through and click on the corresponding PR to see the files that have been changed.

For example, here is a link the the release notes of SuiteCRM 7.11.2:

I am aware of the links in the release notes to the related GitHub issue and fix. But this link is hardly useful for the purpose at hand. Basically, when you install an upgrade, you get a list of files to check. But there is no easy way to go from a file name in that list to either an entry in the release notes or the related issue in Github. Furthermore, the actual configuration that has been customized is done within CRM administration. There is no easy way to relate a file name to an admin menu option or function.

The solution to this would be to either:

  • add a list of concerned file names to each entry in the release notes; or
  • during the upgrade procedure, display a list of functions or menu options to double check, rather than a list of customized files

Personally I think that the release notes are sufficient. It is not just a matter of a list of files but of issues and new fwatures which, in turn re translated to single files.

You could easily create a script that backs-up all your files and compares them with the ones in the upgrade zip and give you at the end a list of files that have been changed. In this way yoy could analyse them before running the upgrade.

Alternatively you could just go to gitHub or Trello and post the request for a new feature, Maybe SalesAgility will do it if you present it positively! :wink: