I've reviewed the yarns for the /projects endpoint, and the corresponding code that implements it. Here are my thoughts:

  • 000.yarn
    • Add links to Ick and yarn home pages.
    • explain the the yarns can be run in either local mode (yarns start a local instance for each scenario) or remote mode (existing remote instance) and how to use ./check to run in either mode
  • 100-projects.yarn
    • the yarn and the architecture spec differ radically in what the project resource should contain; the arch spec seems better
    • otherwise, the scenarios seems OK
  • 200-version.yarn
    • add a note that the yarns are expected to run from a source tree, and the the remote controller is expected to have a compatible version
  • controllerapi.py
    • the code is not very clear, especially when it comes to using local functions to capture local variable/method args; it'd be clearer, I think, to not use that trick
    • would it be clearer and easier to use a more helpful backend than a directory with files? something like Qvarn comes to mind, though it'd require running a Postgres instance and that seems a bit heavyweight
    • decision: stick with the current approach, it's fewer moving parts
    • how strictly should the api validate incoming json resources? it'd be sensible to validate against a specified schema, and json schema seems like it might be plausible, but needs some research.

Tasks:

  • Add link to Ick home page to yarn introduction.
  • Add link to yarn home page to yarn introduction.
  • Add to yarn introduction an explanation of ./check can be used to run in local or remote modes and what that means.
  • Update 100-projects.yarn to use resources that match the arch doc.
  • Update 200-version.yarn with a note about source tree and remote controller version matching.
  • Refactor controllerapi.py to not use nested functions.
  • Add a future task to add resource validation to the controller.