Clarification needed: should include files be relative to current file or containing repository

[Daniel Wagenknecht]

Hello,

in
2077900 includehandler: Fix repo path detection for local includes
the following is stated:
> So far, repository paths for local includes were derived from the path
> name of the config file containing the include, rather than using the
> actual repository root as specified in the documentation.

The documentation though states that for includes without repo specified they
should be interpreted relative to the current configuration file:

───────┬────────────────────────────────────────────────────────────────────────────────
│ File: docs/userguide.rst
───────┼────────────────────────────────────────────────────────────────────────────────
170 │ The specified files are addressed relative to your current configuration file.
... │ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ 8< ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─
259 │ * ``includes``: list [optional]
... │ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ 8< ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─
265 │ * item: string
266 │ The path to a kas configuration file, relative to the current file.
───────┴────────────────────────────────────────────────────────────────────────────────

───────┬────────────────────────────────────────────────────────────────────────
│ File: kas/includehandler.py
───────┼────────────────────────────────────────────────────────────────────────
116 │ The includes can be specified in two ways: as a string
117 │ containing the relative path from the current file or as a
118 │ dictionary. The dictionary should have a 'file' key containing
───────┴────────────────────────────────────────────────────────────────────────

What is the actual desired behaviour?

Sincerely
--
Daniel Wagenknecht

emlix GmbH, http://www.emlix.com
Fon +49 551 30664-0, Fax +49 551 30664-11
Gothaer Platz 3, 37083 Göttingen, Germany
Sitz der Gesellschaft: Göttingen, Amtsgericht Göttingen HR B 3160
Geschäftsführung: Heike Jordan, Dr. Uwe Kracke
Ust-IdNr.: DE 205 198 055

emlix - smart embedded open source

[Jan Kiszka]

On 20.09.21 16:58, Daniel Wagenknecht wrote:
> Hello,
>
> in
> 2077900 includehandler: Fix repo path detection for local includes
> the following is stated:
>> So far, repository paths for local includes were derived from the path
>> name of the config file containing the include, rather than using the
>> actual repository root as specified in the documentation.
>
> The documentation though states that for includes without repo specified they
> should be interpreted relative to the current configuration file:
>
> ───────┬────────────────────────────────────────────────────────────────────────────────
> │ File: docs/userguide.rst
> ───────┼────────────────────────────────────────────────────────────────────────────────
> 170 │ The specified files are addressed relative to your current configuration file.
> ... │ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ 8< ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─
> 259 │ * ``includes``: list [optional]
> ... │ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ 8< ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─
> 265 │ * item: string
> 266 │ The path to a kas configuration file, relative to the current file.
> ───────┴────────────────────────────────────────────────────────────────────────────────
>
> ───────┬────────────────────────────────────────────────────────────────────────
> │ File: kas/includehandler.py
> ───────┼────────────────────────────────────────────────────────────────────────
> 116 │ The includes can be specified in two ways: as a string
> 117 │ containing the relative path from the current file or as a
> 118 │ dictionary. The dictionary should have a 'file' key containing
> ───────┴────────────────────────────────────────────────────────────────────────
>
> What is the actual desired behaviour?

The former. The latter was only internal documentation - and is now
outdated. Please submit a patch to align the code doc to the
authoritative user doc (and now actual behavior).

Jan

[Daniel Wagenknecht]

Hello,

On Fri, 2021-09-24 at 17:58 +0200, Jan Kiszka wrote:
> Please submit a patch to align the code doc to the
> authoritative user doc (and now actual behavior).

I see the authorative user doc (docs/userguide.rst) and the code doc aligning
(include paths for in-tree configuration files are relative to current file),
while the actual behaviour differs since commit 2077900 (include path relative
to repository root).

Taking the user doc as authorative I think

2077900 includehandler: Fix repo path detection for local includes

should be (partly) reverted.

Taking commit 2077900 and its commit message as authorative the user doc and
code doc should be aligned.

Which path should be taken?

[Jan Kiszka]

On 29.09.21 08:39, Daniel Wagenknecht wrote:
> Hello,
>
> On Fri, 2021-09-24 at 17:58 +0200, Jan Kiszka wrote:
>> Please submit a patch to align the code doc to the
>> authoritative user doc (and now actual behavior).
>
> I see the authorative user doc (docs/userguide.rst) and the code doc aligning
> (include paths for in-tree configuration files are relative to current file),
> while the actual behaviour differs since commit 2077900 (include path relative
> to repository root).
>
> Taking the user doc as authorative I think
> 2077900 includehandler: Fix repo path detection for local includes
> should be (partly) reverted.
>
> Taking commit 2077900 and its commit message as authorative the user doc and
> code doc should be aligned.
>
> Which path should be taken?
>

OK, I see now what you mean: The user doc has "relative to the current
file" for

includes:
- some-include.yml

but "relative to the root of the repository" for

incluces:
- repo: my-repo
file: some-include.yml

That is indeed confusing and was never correct, we just flipped from one
model to the other for both. So, everything should be "relative to the
root" now.

Jan