Clarify devfile placement and filename

[kadel]

Which area this feature is related to?

/area documentation

• Clarify the placement of the devfile.yaml in the repository. Is it required for devfile to always be in the root of the project directory / git repository?

• What are acceptable filenames for devfile? Does it always have to be devfile.yaml or devfile.yml?

• precedence rules which one will be selected if we have all the 4 combinations - devfile.yaml / devfile.yml / .devfile.yaml / devfile.yml ?

[vishaltak]

@kadel - Thank you for opening this issue.

Is it required for devfile to always be in the root of the project directory / git repository?

Is this assuming that there will only be 1 devfile for a project? Do we not see the a scenario where there can be 2 devfiles in a project?

Artifact 1
GitHub Codespaces supports .devcontainer.json format and this is what they say in their documentation

You can define a single dev container configuration for a repository, different configurations for different branches, or multiple configurations. When multiple configurations are available, users can choose their preferred configuration when they create a codespace. This is particularly useful for large repositories that contain source code in different programming languages or for different projects. You can create a choice of configurations that allow different teams to work in a codespace that's set up appropriately for the work they are doing.

Artifact 2

https://gitlab.com/gitlab-org/remote-development/gitlab-remote-development-docs/-/merge_requests/11#note_1279032366

---

What are acceptable filenames for devfile? Does it always have to be devfile.yaml or devfile.yml?

devfile is essentially a configuration file. Thus, I would assume it would follow the dotfile convention i.e. .devfile.yaml / .devfile.yml ?

Also, if both .yaml and .yml are acceptable, what to do when both these files are present?

[l0rd]

We should specify a default (e.g. .devfile.yaml) but allow configurability too (for the large repository use case for example). Eclipse Che looks for .devfile.yaml and devfile.yaml but, with the devfilePath URL parameter, supports Devfiles with a different name and path.

For the default name I am in favor of the proposal to follow the dotfile convention: .devfile.yaml (all lowercase).

For the default extension I would support .yaml only based on the YAML spec FAQ.

This has the merit to avoid 2 conflicting devfiles in the same repo.

[elsony]

Also refer to #1071 since some of the items may be addressed as part of the item (or need enhancements)

[maysunfaisal]

We may have documented this usage, I will find out and confirm