Outline the consistent approach for handling paths

[psss]

[psss]

Sync meeting proposed for Thursday.

[psss]

Summary from the sync meeting:

Terminology:

There's a lot of fmf trees being used all around, let's give them some clear names so that we can clearly distinguish what we're speaking about:

user tree

The initial fmf tree from which tmt commands are executed is called user tree. For example:

/home/psss/git/tests/nested

By default it is detected from the current working directory. It can be directly $PWD or the closest parent which contains .fmf directory marking root of the fmf tree as implemented by fmf. Alternatively it can be provided using the --root option.

All the following cases result in the fmf root mentioned above:

tmt --root /home/psss/git/tests/nested
tmt --root /home/psss/git/tests/nested/deeper
cd /home/psss/git/tests/nested && tmt
cd /home/psss/git/tests/nested/deeper && tmt

work tree

When a new run is created, the user tree is copied into the run workdir under the tree folder and its path is made available in the TMT_TREE environment variable. For example this is a runner work tree:

runner:/var/tmp/tmt/run-123/plan/tree

Runner work tree is synced to the guest work tree so that tests defined by the discover shell plugin or prepare shell phases can use files from the user tree.

guest:/var/tmp/tmt/run-123/plan/tree

test tree

The discover plugin prepares tests directory where test scripts and files are available for test execution, let's call it test tree.

The fmf discover plugin copies user tree to test tree when url is not provided. Otherwise the whole git repository is cloned into it.

The shell discover plugin creates a symlink to the work tree:

    ├── discover
    │   ├── default-0
    │   │   └── tests -> ../../tree
    │   ├── step.yaml
    │   └── tests.yaml

Path

The path key of the fmf discover plugin should work in the following three ways:

• if the url key is specified, meaning a tests are fetched from the remote repository, path is handled as a relative path from the git root to the fmf root (possible leading / character in path is ignored)
• if the url is not provided and the path key starts with a slash, it is considered to be an absolute local filesystem path to the directory with tests (allow easy local experimenting)
• if the url is not provided and path does not start with the / character, it is considered to be a relative path from the user tree root (the fmf tree in which the discover step is defined)

The first two cases are supported, the third one is the proposal. Currently the undocumented behaviour is that path: . would take the current working directory or git root when --root option is provided.

In the new implementation escape to the parent directory would be written like this:

discover:
    how: fmf
    path: ..

Similarly, a switch to a sibling fmf tree would look like this:

discover:
    how: fmf
    path: ../other

Handling of the relative path must happen on the original user tree content because work tree does not contain any additional directories except for the copied user tree itself.

Notes

Although undocumented, it is possible that the path: . hack is being used to workaround the inability to escape from nested fmf trees. We should try identify such repositories.

In the archive mode an additional directory which contains the actual repository files might be created (e.g. archives provided by GitHub). In this case the fmf root lies under this extra level and user has to provide path pointing to the actual fmf root. In order to make this scenario easier we could implement a new option to remove the extra level directory for the user.