gvauter commented 1 month ago

“Monorepo” Directory Structure Design Proposal

Authors: gvauter@redhat.com, jpower@redhat.com

Begin Design Discussion: 2024-07-30

Status: draft

Summary/Abstract

This design outlines updates to the repository’s directory structure to establish a clear delineation between the core trestlebot code base and the user interface components. The primary goal is to set up a structure that will allow for the independent management of a core library for building OSCAL automation tooling.

Proposal

This repository’s directory structure will be changed to separate the core trestlebot libraries from the user interface codebase. The user interface modules in /trestlebot/entrypoints will become a top level directory for use as CLI commands or within the container. This also allows further evolution of the entrypoints logic independent of the core libraries as needed. Configuration files used by 3rd party Git and CI providers will be placed under a top level directory.

Design Details

move the /entrypoints directory out of /trestlebot to the repository’s root directory
remove the trestlebot directory from the beginning of the entrypoints listed in the pyproject.toml file under [tool.poetry.scripts]
updated relevant import paths in /tests/trestlebot/entrypoints files
move /tests/trestlebot/entrypoints to /tests/entrypoints/
move contents of /trestlebot/__main__.py to entrypoints/__main__.py
update pyproject.toml to reference the entrypoints module
update import path for entrypoints in tests/testutils.py

Update/Rollback Compatibility

Changes can be rolled back by reverting to the previous commit or individual changes/fixes can be made in subsequent pull requests. No breaking changes are being introduced.

jpower432 commented 1 month ago

Linking some issues that might be impacted or impact this proposal #296 and #286

gvauter commented 3 days ago

Looking at https://github.com/RedHatProductSecurity/trestle-bot/issues/342 this may be a good opportunity to revisit this proposal to support a more flexible CLI implementation. Currently the entrypoints are implemented as standalone commands using argparse, which has served us well, however in order to better support "chained" tasks as needed for https://github.com/RedHatProductSecurity/trestle-bot/issues/342 it might be time to implement a more robust framework. This would decouple the user interface from the "business" logic of each task. The tasks could then be combined/chained together independent of the argument parsing logic.

As an initial proposal, it appears Click would be a suitable option that would allow for a more complex CLI interface. Alternatives such as typer and ilcli could also be explored.

One outcome of implementing a CLI framework would be a uniform command syntax regardless of running as a local Python application or in a container. For example, the trestlebot-autosync Python command and the --entrypoint trestlebot-autosync container entrypoint would both become:

trestlebot autosync <args>

The existing entrypoints would all be nested under the trestlebot top-level command line utility.

@jpower432 @d10n would be great to get your thoughts :bowing_man:

jpower432 commented 3 days ago

@gvauter I agree that this would reduce friction as the CLI gets more complex and improve the CLI UX. I think Click is a good option given its stability and adoption and if we wanted to look at typer there is a migration path from Click.

gvauter commented 3 days ago

Thanks @jpower432! I will put together an ADR to capture the proposed changes.

RedHatProductSecurity / trestle-bot