Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update documentation to specify what kind of thing an ID or DESCRIPTION is #106

Open
willmurphyscode opened this issue Jul 26, 2023 · 1 comment
Labels
documentation Improvements or additions to documentation enhancement New feature or request

Comments

@willmurphyscode
Copy link
Contributor

What would you like to be added:

A lot of yardstick commands accept something like DESCRIPTION or ID, but it's not obvious what this string is. Example:

❯ yardstick label explore --help
Usage: yardstick label explore [OPTIONS] DESCRIPTION

  interact with an label results for a single image scan

Options:
  -y, --year-max-limit TEXT       max year to include in comparison (relative
                                  to the CVE ID)
  -c, --derive-year-from-cve-only
                                  only use the CVE ID year-max-limit
  --help                          Show this message and exit.

In this case, DESCRIPTION is really a result set UUID obtained by running yardstick result list and looking for the image+tool combo the user is interested in. But nothing about DESCRIPTION makes it obvious what to pass in our how to get it.

Why is this needed:

The use of generic parameter names like ID and DESCRIPTION in the docs makes it very hard to come up to speed in yardstick.

Additional context:

@willmurphyscode willmurphyscode added documentation Improvements or additions to documentation enhancement New feature or request labels Jul 26, 2023
@willmurphyscode
Copy link
Contributor Author

A specific example:

❯ yardstick label apply --help
Usage: yardstick label apply [OPTIONS] RESULT_ID

  see which labels apply to the given image and tool pair

Options:
  -i, --inverse                   show image lables that should not be applied
  --id                            show IDs only
  -y, --year-max-limit TEXT       max year to include in comparison (relative
                                  to the CVE ID)
  -c, --derive-year-from-cve-only
                                  only use the CVE ID year-max-limit
  --help                          Show this message and exit.

I assume that --id shows only image IDs, (as opposed to docker tags or whatever?) but this isn't 100% clear from the help text.

Another example:

❯ yardstick label compare --help
Usage: yardstick label compare [OPTIONS] [DESCRIPTIONS]...

  compare a scan result against labeled data

Options:
  --show-fns                 show all FN labels for each tool-image pair
  --show-indeterminates      show each indeterminate result for each tool-
                             image pair
  --fuzzy                    loosen restrictions on package matching
  -r, --result-set TEXT      use a named result set as description input
  -y, --year-max-limit TEXT  max year to include in comparison (relative to
                             the CVE ID)
  -j, --json                 show results as JSON
  --help                     Show this message and exit.

Descriptions of what? What's a description, and where do I get it?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation enhancement New feature or request
Projects
None yet
Development

No branches or pull requests

1 participant