Package structure thoughts

[dgkf]

After having a bit more time to review the package, I just wanted to document a bunch of ideas for next steps. It runs a wide range, from immediately actionable to long-term projects.

val.meter

• Changes already explored in Exploring enhancements to support val.meter transition #5:
  • Use val.meter::pkg as primary object during reporting
  • Simplify parameterization of template
• Metric visualization metadata
  • I think we should add some extra metadata in val.meter when metrics are implemented, which might indicate, for example "lower-is-better", "higher-is-better" and maybe some cutoffs for "okay", "good" and "great" that could be used to indicate some rough measure of quality in the report (eg, color the cards using bootstrap "danger", "warning", "success").

Ease of use

• Restructure primarily around a quarto extension
• Simplify package_report so that it is effectively a thin wrapper around quarto::quarto_render, using our extension and template
• Remove post-processing of file formats (top_page.html) -- if we need extra html, it can be handled in a quarto extension's include-in-header parameter
  • Remove top bar -- if this is needed it should be managed by the overarching webpage, not by the quarto doc. If we want this structure, we could <embed> standalone html reports in a page with a consistent navbar, but it shouldn't be a fixed part of the report

Package artifacts

• Generally, I'd like to remove any binary files in the repo.
  • Logo .png could become .svg, and generally I think it's a good idea to use vector formats for web when possible anyways
  • Remove .Rds files, for examples - generate on the fly, perhaps from test fixtures of a generic testing packages

CSS

• Avoid hardcoding css values, instead deriving from quarto variables or bootstrap variables so that our themes can be customized

Use in val.repo

• Move away from storing package reports in the same repo as our github actions for maintaining the repo
  • Avoid repo size bloat due to md and html documents
  • Avoids complexity of juggling static artifacts in same repo as PACKAGES
• To view packages, I think we might want to consider a separate website that fetches the PACKAGES file and renders a dynamic page for a given package:
  • read (and cache) the PACKAGES index
  • parses the dcf file and renders a package-specific data

[llrs-roche]

@dgkf Many thanks for the feedback! I answered below and as you can see I created some "sub-issues" to address what you pointed out:

After having a bit more time to review the package, I just wanted to document a bunch of ideas for next steps. It runs a wide range, from immediately actionable to long-term projects.

val.meter

• Changes already explored in Exploring enhancements to support val.meter transition #5:

  • Use val.meter::pkg as primary object during reporting
  • Simplify parameterization of template

I agree, it has become too much. I opened an issue #11, but we might need to keep it open to extensions from companies or setups.

• Metric visualization metadata

  • I think we should add some extra metadata in val.meter when metrics are implemented, which might indicate, for example "lower-is-better", "higher-is-better" and maybe some cutoffs for "okay", "good" and "great" that could be used to indicate some rough measure of quality in the report (eg, color the cards using bootstrap "danger", "warning", "success").

That might be good but that's for val.meter (and be aware of color blindness)

Ease of use

• Restructure primarily around a quarto extension

I like that idea, but we will still need to have a template.

• Simplify package_report so that it is effectively a thin wrapper around quarto::quarto_render, using our extension and template

Agreed, but much of what's in package_report is to deal with the way quarto handles rendering files. There might be some misunderstanding from my part or some development that makes now possible to be leaner, so I opened an issue for it #12

• Remove post-processing of file formats (top_page.html) -- if we need extra html, it can be handled in a quarto extension's include-in-header parameter

This should be covered with #12 and the extension but I opened an issue #13 to remember about this.

• Remove top bar -- if this is needed it should be managed by the overarching webpage, not by the quarto doc. If we want this structure, we could <embed> standalone html reports in a page with a consistent navbar, but it shouldn't be a fixed part of the report

Agreed, the html should work standalone too and then the website handle the top bar #13

Package artifacts

• Generally, I'd like to remove any binary files in the repo.

  • Logo .png could become .svg, and generally I think it's a good idea to use vector formats for web when possible anyways
  • Remove .Rds files, for examples - generate on the fly, perhaps from test fixtures of a generic testing packages

I have mixed feelings on this one. Having a fixed .RDS makes it more reproducible to test features. If we generate metrics on the fly we might get new unexpected errors.

CSS

• Avoid hardcoding css values, instead deriving from quarto variables or bootstrap variables so that our themes can be customized

I agree, on #2 I tried to do that to make it easier to customize.

Use in val.repo

• Move away from storing package reports in the same repo as our github actions for maintaining the repo

I think it makes sense to have in a single git repository all related info. But if we move away were do you suggest to store the information?

• Avoid repo size bloat due to md and html documents

Currently on the website we store the .md and when the website is updated the new html are generated.

• Avoids complexity of juggling static artifacts in same repo as PACKAGES

I was playing with the idea of the repo with PACKAGES have as artifacts the metrics (for 30 days). What do you think? In principle the metrics could be restored from the PACKAGES but warnings, logs and similar "metadata" won't be so easy to recover. Timings of the GHA can be recovered via the API see llrs-roche/gh_actions_tracking

• To view packages, I think we might want to consider a separate website that fetches the PACKAGES file and renders a dynamic page for a given package:

  • read (and cache) the PACKAGES index
  • parses the dcf file and renders a package-specific data

That could work for the metrics but harder to do with the check logs.