2026-07-17 –, Thomas Swain Room
Nobody loves writing release notes... and it only gets worse when multiple institutions are editing the same file. We learned the hard way that using a single file, manual RST editing, and no validation leads to repeated merge conflicts every release cycle. In response, we built Brassy, a CLI tool that replaces single-file changelogs with per-change YAML files, assembles them into formatted release notes, and lints entries in CI. We also built PinkRST (an RST formatter) and a Python-based Sphinx build system to tie our large multi-institution and many repo software documentation together. This talk covers the tools, the integration, and what we learned about getting scientists to actually write documentation.
We work as part of a multi-institutional team developing a newly open-sourced 17-year-old package for processing geolocated satellite and weather data. The package has dozens of plugin repositories, contributors across institutions, and operational users in the US Navy who depend on it for near-real-time tropical cyclone imagery.
Once GeoIPS (Geolocated Information Processing System) was open-sourced, release notes became a huge pain point. Contributors would all edit the same reStructuredText (or at times, markdown) file by hand in different pull requests. There was no auto-enforceable standard format. No linting. Lots of merge conflicts. Consequentially, important changes slipped through undocumented and formatting varied wildly.
We built three pieces of infrastructure to fix this, each of which is open-source, pip-installable, and lightweight.
First we built Brassy (Build Release Assembler for Sane Software with YAML). Brassy swaps a shared changelog file for individual YAML files with one per change. For each , the contributor fills out a structured template (title, description, category, affected files, linked issues, etc.) generated by Brassy. At release time, Bbrassy assembles the changelog fragments into sphinx-compatible formatted RST. One file per change means near-zero merge conflicts and easy application of a change to this release or the next. Brassy also provides quality of life functionality by generating templates pre-populated with git-tracked file changes, pruning empty sections, and running as a CI linter to catch formatting problems on every pull request before they land.
Secondly, we created pinkrst, an opinionated RST formatter in the spirit of Black for Python. It handles tedious autoformatting of reStructuredText for doc8 compatibility (line wrapping, whitespace cleanup, and consistent formatting of lists, headers and codeblocks) of the generated release notes.
Third, we developed a more robust Python-based Sphinx build system. GeoIPS previously relied on a complex bash script to build documentation across its core package and many plugin repos. We replaced it with a Python builder that calls Brassy to assemble release notes from YAML directories, runs pinkrst to format the output, generates API docs for multiple packages via sphinx-apidoc, and builds multiple repos into final HTML. This pipeline handles docs for both the core GeoIPS package and any plugin, using shared templates, CI workflows and configuration.
Tools alone don't solve documentation problems... For better or worse, people must actually use them! GeoIPS plugin writers are primarily scientists, not software engineers. Like many scientific projects, the codebase grew a lot faster than its docs and did so for for years. We'll talk about what worked: lowering the barrier, clear guidelines on "what" goes "where," catching problems early, and making standards obvious enough that contributors rarely need to ask.
This talk is for anyone maintaining a multi-team open-source project . We will cover how per-change changelogs outperform single file release notes in distributed teams, how CI linting of non-code artifacts enforce standards without slowing people down, and do our best to offer practical advice for introducing new tooling into a project where no single team is the “leader.”
Gwyn Uttmark serves at Colorado State University and has more than a decade of expertise in open-source scientific software development. Gwyn currently works with the Cooperative Institute for Research in the Atmosphere to make the US Navy-born GeoIPS an accessible and effective platform for open-source development communities and academic researchers.