Should `qlpack.yml` `compileForOverlayEval` be documented?

[Marcono1234]

Description of the issue

The qlpack.yml / codeql-pack.yml file supports a property called compileForOverlayEval. This property is in the automatically generated qlpack.yml file when using the VS Code extension or codeql pack init. However, the property is not documented anywhere, neither here in this repository nor on https://docs.github.com/en/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs#qlpackyml-properties

It would be good to either document the property or (if it is too low-level) not include it in the automatically generated qlpack.yml file. Otherwise it might be confusing to users what the purpose of this property is.

[hvitved]

I believe this property is still only used internally, but yes, it should be documented once it is public (cc @jbj ).

[jbj]

Yes, this property is currently only for internal use. When we're through the transition phase where we set the property on all our first-party packs, it's fairly likely that we'll switch it to be set by default and impossible to turn off, so therefore this property may never need to be documented.

[Marcono1234]

Thanks for the explanation! Would it make sense then to omit the property from the qlpack.yml file generated by the VS Code extension and by codeql pack init (if that is technically possible during the transition phase) to avoid confusion for users?

switch it to be set by default and impossible to turn off

This might be a problem then for custom queries by users where compileForOverlayEval: false is the default in the generated qlpack.yml file, unless they will still be allowed to turn compileForOverlayEval off.

If you don't think that this is a problem (and that no documentation is needed), feel free to close this GitHub Issue. At least other users might now find the information in this issue here for now.

[jbj]

I wasn't aware that our tooling is emitting compileForOverlayEval in generated QL packs. Thanks for letting me know!

I've raised this internally with the relevant developers, but it might take us a while to come to a conclusion because many folks are on summer holiday. I'll keep this issue around until we have a decision on whether we want to change anything.