Evaluation - Document options of SAST, DS automatically [ end result, do not proceed ]
Investigation Closing note
end result, do not proceed
Problem to solve
SAST, Dependency Scanning (DS) and their analyzers provide many options that need to be documented, but keeping the documentation up-to-date is a challenge given the many projects involved (15+ projects). A solution is to generate automatically the doc section covering the options of SAST & DS.
Further details
Currently the options exposed by SAST and DS include:
- the options exposed by common/orchestrator and shared by the orchestrator
- the generic options defined in common/command and shared by the analyzers
- the specific options defined by the analyzer, like the ones defined for spotbugs
Overall documenting these options involve keeping track of about 15 different projects. We should generate the doc automatically or at least implement checks to ensure that the doc is up-to-date and covers all the available options.
Proposal
- in the analyzers, introduce a new "list options" sub-command that documents the options exposed by the analyzer;
this sub-command should be added to the
common/commandto ensure consistency across analyzers - in SAST and DS, introduce a related "list options" sub-command that iterates over the available analyzers
(over the Docker images really) and call the "list options" sub-command to collect all the available options;
this new sub-command should be implemented in
common/orchestrator, which is the Go sub-package SAST and DS are currently based on - in the CI configuration of SAST and DS, add a job that leverage the "list options" command to update the docs
What does success look like, and how can we measure that?
It takes little time, or even no time to document the new options of SAST, DS or their analyzers in GitLab EE.
Links / references
See https://gitlab.com/gitlab-org/gitlab-ee/issues/10120#note_159303356