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

5 views
Skip to first unread message

Daniel Wagenknecht

unread,
Sep 20, 2021, 10:58:15 AM9/20/21
to kas-devel
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

unread,
Sep 24, 2021, 11:58:09 AM9/24/21
to Daniel Wagenknecht, kas-devel
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

unread,
Sep 29, 2021, 2:40:01 AM9/29/21
to Jan Kiszka, kas-devel
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?
signature.asc

Jan Kiszka

unread,
Sep 29, 2021, 5:10:20 AM9/29/21
to Daniel Wagenknecht, kas-devel
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
Reply all
Reply to author
Forward
0 new messages