documentation added in e5a1280 seems to be wrong #204

New Issue

ungleich-gitea · 2021-11-20T15:21:25Z

ungleich-gitea commented

2021-11-20 15:21:25 +00:00

Created by: asteven

e.g. the first sentence below is simply wrong:

This also means that the "__link" command must make sure, that either
"__file/etc/cdist-configured" allready is present, or, if it's not, it needs
to be created. The task of cdist is to make sure, that the dependency will be
resolved appropriately and thus "__file/etc/cdist-configured" be created
if necessary before "__link" proceeds (or to abort execution with an error).

The "__link" command does not make sure anything and does not create other objects or the like. All in all the added docs give the user the idea that the type commands (e.g. __link) are executed/applied in order like in a script, which is not how cdist works at all.

*Created by: asteven* e.g. the first sentence below is simply wrong: This also means that the "__link" command must make sure, that either "__file/etc/cdist-configured" allready is present, or, if it's not, it needs to be created. The task of cdist is to make sure, that the dependency will be resolved appropriately and thus "__file/etc/cdist-configured" be created if necessary before "__link" proceeds (or to abort execution with an error). The "__link" command does not make sure anything and does not create other objects or the like. All in all the added docs give the user the idea that the type commands (e.g. __link) are executed/applied in order like in a script, which is not how cdist works at all.

ungleich-gitea added the

Stale

label 2021-11-20 15:21:25 +00:00

ungleich-gitea closed this issue

2021-11-20 15:21:25 +00:00

ungleich-gitea commented

2021-11-20 15:47:51 +00:00

closed

ungleich-gitea commented

2021-11-20 15:47:52 +00:00

Created by: tpo

asteven wrote:

documentation added in e5a1280 seems to be wrong

e.g. the first sentence below is simply wrong:

This also means that the "__link" command must make sure, that either
"__file/etc/cdist-configured" allready is present, or, if it's not, it needs
to be created. The task of cdist is to make sure, that the dependency will be
resolved appropriately and thus "__file/etc/cdist-configured" be created
if necessary before "__link" proceeds (or to abort execution with an error).

The "__link" command does not make sure anything and does not create other objects or the like.
All in all the added docs give the user the idea that the type commands (e.g. __link) are
executed/applied in order like in a script, which is not how cdist works at all.

I apologize for the unclear documentation that I've contributed. Let's remove the sence "This also means that the "__link" command must make sure...". Does this improve that paragraph for you so that it correctly expresses what's going on? I.e. :

On line 4 you can see that the instantion of a type "__link" object needs
the object "__file/etc/cdist-configured" to be present, before it can proceed.

The task of cdist is to make sure, that the dependency will be
resolved appropriately and thus "__file/etc/cdist-configured" be created
if necessary before "__link" proceeds (or to abort execution with an error).

The reason why I added that paragraph is, that - as far as I can see - nowhere in the cdist documentation is explained how dependencies ("requires") should be used, nor how the dependency resolution mechanism works. The dependency resolution mechanism however is the core feature of cdist and it is crucial that the user understands the semantics and possibly also the mechanics of this feature.

When I wrote that paragraph I did check the code to see, how dependency resolution works. I forgot that now and I'm too lazy to look it up now - however AFAI remember it is the __link command itself that hooks into the cdist "engine" and adds those dependencies. Only after the "root" manifest has finished execution will the cdist "engine" collect all the dependencies, resolve them and then run all the gencode stuff in the right order to execute whatever is necessary. It might be that my recollection of how cdist works internaly is wrong, however, that is not important for the point I'm trying to make here, which is:

the user should understand from a conceptual point of view how cdist works (that would be the last paragraph above that I just wrote up) and
the user should understand the semantics of 'require="__cmd/object_id" __cmd --foo bar object_id2'

I my docu addition I was trying to explain point 2. Point 1. should be addressed as well.

If you agree then let's dump that first sentence of the paragraph. Or if you can come up with a better explanation, then please do. However I'd sugest to allow the docu to improve even by small steps and mind the saying "the perfect is the enemy of the better".

Thanks Steven!
*t

*Created by: tpo* asteven wrote: > documentation added in e5a1280 seems to be wrong > > e.g. the first sentence below is simply wrong: > > This also means that the "__link" command must make sure, that either > "__file/etc/cdist-configured" allready is present, or, if it's not, it needs > to be created. The task of cdist is to make sure, that the dependency will be > resolved appropriately and thus "__file/etc/cdist-configured" be created > if necessary before "__link" proceeds (or to abort execution with an error). > > The "__link" command does not make sure anything and does not create other objects or the like. > All in all the added docs give the user the idea that the type commands (e.g. __link) are > executed/applied in order like in a script, which is not how cdist works at all. I apologize for the unclear documentation that I've contributed. Let's remove the sence "This also means that the "__link" command must make sure...". Does this improve that paragraph for you so that it correctly expresses what's going on? I.e. : ``` On line 4 you can see that the instantion of a type "__link" object needs the object "__file/etc/cdist-configured" to be present, before it can proceed. The task of cdist is to make sure, that the dependency will be resolved appropriately and thus "__file/etc/cdist-configured" be created if necessary before "__link" proceeds (or to abort execution with an error). ``` The reason why I added that paragraph is, that - as far as I can see - nowhere in the cdist documentation is explained how dependencies ("requires") should be used, nor how the dependency resolution mechanism works. The dependency resolution mechanism however is _the_ core feature of cdist and it is crucial that the user understands the semantics and possibly also the mechanics of this feature. When I wrote that paragraph I did check the code to see, how dependency resolution works. I forgot that now and I'm too lazy to look it up now - however AFAI remember it _is_ the __link command itself that hooks into the cdist "engine" and adds those dependencies. Only _after_ the "root" manifest has finished execution will the cdist "engine" collect all the dependencies, resolve them and then run all the gencode stuff in the right order to execute whatever is necessary. It might be that my recollection of how cdist works internaly is wrong, however, that is not important for the point I'm trying to make here, which is: 1. the user should understand from a _conceptual_ point of view how cdist works (that would be the last paragraph above that I just wrote up) and 2. the user should understand the _semantics_ of 'require="__cmd/object_id" __cmd --foo bar object_id2' I my docu addition I was trying to explain point 2. Point 1. should be addressed as well. If you agree then let's dump that first sentence of the paragraph. Or if you can come up with a better explanation, then please do. However I'd sugest to allow the docu to improve even by small steps and mind the saying "the perfect is the enemy of the better". Thanks Steven! *t

Sign in to join this conversation.