[CERTTF-424] feat: support a reference directory for attachments

[boukeas]

Description

At the moment, when Testflinger attachments are not specified through absolute path names (in the local field) they are interpreted relevant to the current working directory. This is quite restrictive and becomes an inconvenience especially when Testflinger jobs and their attachments are created in Github workflows and submitted through the Testflinger submit Github action.

This PR:

• Changes the default behaviour to interpret relative attachment path names against the directory where the submitted job file is located.
• Introduces the --attachments-relative-to command-line argument to the Testflinger CLI, for specifying the directory that relative attachment path names will be resolved against.
• Introduces a new input to the Testflinger submit Github action, corresponding to the new command-line argument
• Adds documentation for the additional CLI and Github action arguments

Resolved issues

Resolves CERTTF-424.

Tests

• Manual tests in a local Testflinger deployment
• New unit tests have been introduced to test attachment packing, including packing when a reference directory is provided.

Changes to the Github submit action can only be tested once the updated Testflinger CLI snap has been deployed.

[plars]

This looks fine to me, and I'm +1 on it but just one question...
Was attachments-relative-to-job-file specifically requested in addition to attachments-relative-to? It feels a bit overkill to have both. I mean... I get it, but I also feel like it's not that hard for the submitter to specify the dir where the attachments are if they are also already specifying the same dir in the path to the job file. Curious what your thoughts are about that and how critical it seemed to have both? I know you talked to Max about though, so perhaps there's something that I'm not considering.

[boukeas]

This looks fine to me, and I'm +1 on it but just one question... Was attachments-relative-to-job-file specifically requested in addition to attachments-relative-to? It feels a bit overkill to have both. I mean... I get it, but I also feel like it's not that hard for the submitter to specify the dir where the attachments are if they are also already specifying the same dir in the path to the job file. Curious what your thoughts are about that and how critical it seemed to have both? I know you talked to Max about though, so perhaps there's something that I'm not considering.

The request by @Hook25 was specifically for something like attachments-relative-to-job-file. I simply wanted to generalise that since the request is essentially a special case of the more general feature that attachments-relative-to offers.

I wouldn't say it's critical to have both but it feels like a shame to specify two arguments (the reference path and the job file) that would be almost identical if the job file is in the reference path.

[Hook25]

I don't think its critical to have both but setting them in CI is not super handy (quite the opposite actually) so to have a simple boolean it is way better for me. Also, I suggested this as the attachment mechansim attaching from the cwd is counterintuitive to me. I expected it (and I still think it should) be relative to the job file by default, as that is what most tools do when they get an input recipe

[boukeas]

I expected it (and I still think it should) be relative to the job file by default, as that is what most tools do when they get an input recipe

I think that's a fair point that I hadn't considered appropriately before. Indeed, examples like HTML or LaTeX files interpret relative paths as relative to the location of the input file. @plars would you object to removing the --attachments-relative-to-job-file flag altogether and making this behaviour the default? The current default, i.e. using the current working directory as a reference, would be easily selected using the --attachments-relative-to argument.

[plars]

I don't think its critical to have both but setting them in CI is not super handy (quite the opposite actually) so to have a simple boolean it is way better for me.

I was kind of assuming it would be something like:

JOB_PATH=/root/of/jobs/and/attachments
testflinger submit $JOB_PATH/job.yaml --attachments-relative-to $JOB_PATH

I suspect you're right that in practice, attachments will probably be in the same location as the job file most of the time. However I'm reluctant to change it from defaulting to CWD because:

1. It's a change from the current behavior
2. It's a change from expected behavior of most CLI programs (i.e. when you don't give a path, CWD is assumed)

If something like the above snippet doesn't work for just keeping --attachments-relative-to as the primary mechanism to do this, then I'm fine with just landing this as-is.

[boukeas]

It's a change from expected behavior of most CLI programs (i.e. when you don't give a path, CWD is assumed)

@plars that's exactly how I approached it when I made the initial choice to use the CWD but I believe I was wrong (and that's the reason why I am insisting we should revert that choice and change the default behaviour). I believe this is not an issue of where a CLI program manipulates its own files, in which case using the CWD would indeed be the convention. This is a case of how relative links in the input file are interpreted. The best example of a similar example I can think of is HTML. Regardless of the browser you are using or the CWD, relative references in an HTML file are always interpreted in relation to the HTML file. And that makes a lot of sense for a myriad reasons there is no point in repeating. We need the additional flexibility here, i.e. we need the --attachments-relative-to argument, but I really think the default should be what is now the --attachments-relative-to-job-file behaviour.

[boukeas]

This has stagnated for a while so I thought I'd take the executive decision to:

• remove the --attachments-relative-to-job-file argument
• make that behaviour the default, i.e. relative path attachments are interpreted in relation to the job file, in line with similar approaches to interpreting relative paths in e.g. HTML files.
  I have also asked for some feedback on MM around this feature and received another response in favour of this approach.

[plars]

Looks good, thanks for the updates to the docs and the tests too! If "Mr Hook25" (@Hook25) is good with it, then let's merge it! :)