New stacks loading policy

[ghost]

Required for eclipse-che/che#5234

[slemeur]

We probably need to link/reference to the section bellow which is explaining stacks in a custom assembly.

[ghost]

Right now we don't have an convenient way to provide custom stacks in custom assemblies. There's an issue that needs to be done though - eclipse-che/che-archetypes#20

Existing users won't be affected.

[slemeur]

Custom assemblies are able to define their own stacks.json.

Also the description is misleading. It is using "update", while what will happen is that all the existing stacks will be wipeout and completely reinitialize with the content of the stacks.json.

We need to explain to the user how:

• he can get the new stacks from upstream
• and keep the stacks that he added.

[ghost]

We don't have a clean nice way - this needs to be done eclipse-che/che-archetypes#20

Stacks are kept in a database - no need to do anything.

[slemeur]

Even if it is not clean, it will still be needed for those who are creating custom Che. So either eclipse-che/che-archetypes#20 was a pre-requisite for merging eclipse-che/che#5234 or we provide documentation to explain how to handle that until eclipse-che/che-archetypes#20 is fixed.

Also "update" will mislead the user. The "update" must be completely explicit and clear to the user - so that he will know that when configuring the property, the system will wipeout all stacks currently in the product. Including those that he added manually. So he will cautiously configure that property.

It must also explain to the user how he can get stacks from a new version of Che and not loose the one he added. Here again, even if the way we handle that is not nice, etiher we have fixes that are coming and we make them pre-requisite for merging eclipse-che/che#5234 or we provide documentation to explain how it can be handled.

[slemeur]

Need to describe the property in the "configuration.md" page as it explains most of the che.env properties and then link to the explanation from here.

[ghost]

Added CHE_PREDEFINED_STACKS_RELOAD__ON__START to config.md

[slemeur]

Need to explain what is the json and where it is.

[ghost]

We do not want to expose this json to a user. It is hidden in JAR resources, and this is by design.

[slemeur]

So how can I alter the stacks list? How can I get a new stacks provided on a new version of Che without loosing my stacks?

This needs to be explicit in the docs.

[ghost]

@slemeur

Special warning, this must be done cautiously because the database of stacks will be wipeout (including the ones you added) and will be reinitialized with the stacks.json.

Unfortunately, this is not true. The way, stacks are uploaded to a db hasn't changed. So, if you had stack A, B, C in your db, and the new JSON has untouched A, B, updated C and a new stack D, the db will have untouched A,B, updated C, and a new stack D in the end. If the new JSON has just one stack E, it will be added to a db, and the old ones will be kept.

If you want to upgrade to a newer version of Che and keep the stacks you added and benefit from the new stacks added you need to manually edit the stacks.json and follow the instructions on this documentation

Again, this is also not true due to #1. Besides, stacks.json is hidden from a user. It's part of binaries now. A user does not edit it and does not even know where it's located. So, users of default Che assemblies will interact with stacks API only through UD or any other clients. And to benefit from new stacks, just set the env value to true (conflicts are possible though and it's worth mentioning in docs).
The only way to have custom stacks.json for users with custom assemblies is to add https://github.com/eclipse/che/tree/master/ide/che-core-ide-stacks module to a custom assembly. I do not see any value in documenting it now, since eclipse-che/che-archetypes#20 will fix it anyway, and fix it as nicely as archetypes can (@skabashnyuk takes it to the next sprint)

[slemeur]

Sorry @eivantsov, you might be right and that would even be a great news. But actually this is not what I understand from the root issue.

See @gazarenkov statements:

We implement the simplest case of merging which for example just replacing stacks DB with stacks.json content (remove and add) or something else but simple"

and also:

2/ If you need stacks database to be changed every restart you can configure the CHE_PREDEFINED_STACKS_RELOAD__ON__START=true in che.ev file.

In the docs you are writing:

When set to true, json is sourced every time Che server starts.

It is not clear what will happen: whatever the update policy is, it needs to be explicit and clear to the user.

Again, this is also not true due to #1. Besides, stacks.json is hidden from a user. It's part of binaries now. A user does not edit it and does not even know where it's located. So, users of default Che assemblies will interact with stacks API only through UD or any other clients. And to benefit from new stacks, just set the env value to true (conflicts are possible though and it's worth mentioning in docs).

Yes, that's the point, the new way has to be explained.

The only way to have custom stacks.json for users with custom assemblies is to add https://github.com/eclipse/che/tree/master/ide/che-core-ide-stacks module to a custom assembly. I do not see any value in documenting it now, since eclipse-che/che-archetypes#20 will fix it anyway, and fix it as nicely as archetypes can (@skabashnyuk takes it to the next sprint)

Disagree - it has to be explicit in the docs because I don't know a single custom Che which is not doing that. I'm happy there will be a better solution, but docs will have to be updated accordingly when the better solution will be in place.

[ghost]

I committed to this branch with more explanations. And @mkuznyetsov has already started working on stacks archetypes. -1 for documenting smth that won't exist pretty soon. I don't think this issue takes much time.

[slemeur]

Documentation must be aligned with the current state of the product.

AFAIU there is some rush around this work. Few hours the issue was planned for the next sprint - and now someone already started to work on it. Nice.

If it gets done before the release, that is good we'll have docs for the new archetype capability. If it is not, product documentation needs to be aligned with the product and documentation about how to handle without the archetype will be needed.

[ghost]

Agreed. Docs on adding https://github.com/eclipse/che/tree/master/ide/che-core-ide-stacks into a custom assembly should be quite simple.

[slemeur]

Sorry that has been merged while few feedbacks were not handled and PR not approved?

• The upload policy has to be clarified so that the user can clearly understand what is going to happen when CHE_PREDEFINED_STACKS_RELOAD__ON__START is activated.

Then from the latest edits:

• Where is the doc for the archetype type here: https://github.com/eclipse/che-docs/blob/master/src/main/_docs/assemblies/assemblies-assembly-lifecycle.md#archetypes-list ?
• Should we not provide links to the user so that he can jump into the archetype docs and learn more about those?
• From the informations added, it is unclear, it just says that it is possible, but it does not help to understand how.

[ghost]

I'll open a new PR with improvements.