add design decision include path

[RolandJentschETAS]

add design decision include path

[github-actions]

Documentation preview for this pull request is available at:
pr-3196: https://eclipse-score.github.io/score/pr-3196/

[anmittag]

TLC 2026-08-20: @qor-lb , @arsibo please review

[aschemmel-tech]

Option B conflicts with DR-003-proc (as in #3194).

[LittleHuba]

I find this proposal heavily skewed towards a pitchfork layout (option B) (even clearly stating pitchfork layout in the evaluation criteria. Based on that, I find it hard to base a discussion on this, since it feels like the arguments were written based on the decision instead of the other way round.

From my comments you can probably guess that I'm clearly leaning towards option A. And this review felt like a uphill battle from the start. Looking just at the advantages/disadvantages of options A and B, the evaluation should not be leaning so heavily towards option B.

Two sources for reference why I heavily prefer option A:

1. https://bazel.build/tutorials/cpp-use-cases where the pitch fork layout is clearly only stated as a legacy adoption use case. This means that Bazel is not built for this project structure and that you will feel lots of friction trying to use it.
2. https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1204r0.html#src-dir has a full section just talking about why pitch fork layout is bad and should not be used

Side note: I appreciate the accepted alternative that will safe communication and baselibs from having to rewrite 90% of their code. I still do not feel comfortable agreeing with the final decision because of the consequences for the overall project.

[aschemmel-tech]

Thanks for the rework, option A selected matches with DR-003-proc

[FScholPer]

We should also encounter how we check new sources and monitor the structure

[LittleHuba]

There was some work in clang-tidy that went in this direction but was never finished:
llvm/llvm-project#63226

[LittleHuba]

Not quite sure how prescribing this impl package makes things better/worse.
While we have this pattern in mw::com, it is honestly a lie to some extent (see https://github.com/eclipse-score/communication/blob/main/score/mw/com/types.h).

For mw::com this is something we will probably never change, but other libraries might not want that pattern.

Before we make users deduce public API from directory structures we should actually provide clear documentation with the public interface. In communication we work with breathe, Sphinx and these tags to mark public API: https://github.com/eclipse-score/communication/blob/main/score/mw/com/types.h#L37

TL;DR: I vote for removing the impl package guideline in favor of describing the public API via tagging and a generated documentation, while leaving projects to come up with a good source structure based on their architecture.

[RolandJentschETAS]

@LittleHuba : I can change it in a way, that this is optional to isolate the private headers/sources in an impl folder ? Would that be better ? Or complete remove it ?

[qor-lb]

As discussed in Weekly 2026-09-21 this was onboarded to the FEP process. #3269 tracks also the implementation once the DR is agreed.

@LittleHuba let me know once it is ready for the FCP and then I will do the announcement and facilitate the alignment.