CommandBox is a great product, and it is always improving. Recently, one of those improvements threw a MASSIVE wrench in my world, and it might affect you too. Long story short, ContentBox stores custom modules, themes, widgets inside of the ContentBox module, usually with some tricky gitignore magic, you can ignore the core, and just commit your custom code to your repo. Now, after an update to CommandBox ( 3.9 ), if you do a install contentbox --force to update ContentBox around your changes, you might be surprised when CommandBox deletes all of your ContentBox modules, all of your ContentBox themes, all of your ContentBox widgets. Why CommandBox hates us all of a sudden?

Why does CommandBox hate us?

Actually, CommandBox doesn't hate us. CommandBox is awesome, and one of the more recent updates changed how it installs modules. Let's be frank, it’s a good update… it just isn't good for the way ContentBox is/was working. When installing modules, CommandBox checks to see if it is installed ( if a folder is present in the installation directory that matches ), if it is installed, it moves on. If not, it installs the module. No real changes there.

If you run a install --force,  CommandBox used to install the module over the existing folder if it existed, essentially a copy and paste. After this recent update, to keep your folder system clean, a force will actually remove the entire folder, and then install the module again. This way you don't get orphaned files and folders, and the module will work as expected, without remnants causing complications. This gets really messy with java jars, and you can read more about the ticket behind this update here - https://ortussolutions.atlassian.net/browse/COMMANDBOX-640

Issue with ContentBox

The issue is, ContentBox was initially designed before CommandBox was created, and for backwards compatibility and not changing things for the sake of changing things, a lot of the original design decisions are still in place. One of those decisions was the conventions and systems for dealing with building ContentBox modules, ContentBox admin modules, ContentBox widgets, ContentBox Themes. All of these have specific locations, all inside of the ContentBox module itself. So if you update ContentBox with CommandBox ( version 3.9 or higher ), CommandBox will delete all of those custom items. 

How do we upgrade then?

If you have Source Control, and your custom code is committed, upgrading is simple, albeit frustrating. Make sure all of your custom code is committed. Run the install contentbox --force and then after the upgrade is run, you can go to your source control and discard all the deleted files, restoring them for you.

If you are not using Source Control, this is another use case for why you should be using it. You can copy your assets out of your ContentBox module folder, and then upgrade and copy them back.So start using it now!

That solution is not ideal - what is Ortus doing about it?

Luis and I ( mainly Luis ) have been working on extending ContentBox to support the old locations for backwards compatibility and core features, while creating a new set of conventions for all of your custom code, so you are not affected by this moving forward.

This convention is currently in the bleeding edge, and is being tested thoroughly at this point, but it is not quite ready for release. When released, the new convention will give you a new module for all of your custom code. You will be able to store ContentBox themes, ContentBox widgets, front end and admin ContentBox modules all in this new module. Since this new module convention will be outside of the ContentBox module itself, upgrades will no longer affect any of your custom ContentBox code, and ContentBox will know how to locate all of your themes, widgets and modules.

How do we upgrade to this new convention?

This is not finalized yet, so at this time we do not recommend upgrading to this new convention. If you would like to test out the changes, please reach out to us if you have any issues trying the bleeding edge.

When these changes are finalized, and released, we will give you very specific instructions, including some videos to try and make this update as smooth as possible.

We apologize for the inconvenience this may have caused you. We can blame Brad for being so quick to turn out CommandBox updates, he beat us out with this one, and we had to play catch up. Again, for the record, the update was a good update for CommandBox but ContentBox wasn't ready for such a change.

We'll be releasing these changes soon. Keep an eye out on a blog post about the update, and how to apply it.
Thanks everyone.