@rmcd @dblodgett @ahopkins1 @aaufdenkampe_limno.com @sjordan_limno.com @kbartels_limno.com

Background

This refactoring work was originally outlined under issue #13 (closed). As the list of desired refactoring pieces grew and closure criteria for that issue were developed, it became apparent this effort is too large for a single issue to capture. The single issue would make it more difficult to organize the work and decipher which changes are related to which aspects. Therefore we are opening this milestone and converting the closure criteria into individual issues.

Why a Refactor is Necessary

Aspects of the builder repo are complex and not adequately documented. This impacts the general usability of the repository, as well as adds difficulty to the maintenance and on-boarding of new staff/contributors. Below are some additional background on specific aspects of the repository.

Complexity

This repo is designed to build three separate images with different configurations of pygeoapi. As currently structured, the repo splits out shared dependencies into multiple files. In theory, separating out these files provides better performance by allowing base dependencies to be built into an image once and then shared between the other images. In practice, this time savings is really only relevant for our CI/CD deployments and can actually hinder development time. During development it is difficult to tell which set of images will be impacted by changes; leading to situations where developers often had to go back further in the pipeline and rebuild the base or conda images to actually see changes reflected. The result was multiple builds were required before they could test their changes, or in worse cases confusion about why changes did not address the problem (when it was just that they were not loaded into the image). The caching feature of docker build should also provide much of the benefit that multiple files does (as least during development).

Documentation

The documentation for this repo has not been sufficiently updated to reflect recent changes from the previous development sprints. Additionally, the documentation is large incomplete or scattered; requiring new developers to piece together information from multiple sources to understand how execute the builder repository. Incomplete list of documentation includes.

• Main README.md for builder - some additional environment setup information
• PLUGINS.md - provides context for how to setup environment and incomplete explanation for nox works
• Docker specific README.md - instructions how to run containers with docker, though only partially correct.
• SERVER.md - some server information, but also explains some of the compose.yml/docker-compose.yml settings?

Workflow

Individual issues can be tackled on new feature branches and then synced back to the refactor branch which will use to consolidate the changes before issuing a single PR back to main at the conclusion of this milestone.