Lessons Learned when Open-Sourcing a Large Existing Code Base: The Kaiju Experience

“8 Simple Rules”: Lessons Learned from Open-Sourcing kaiju at the CGS Eric Winter Center for Geospace Storms Johns Hopkins University Applied Physics Laboratory 11 August 2025 Outline • I am a Research Software Engineer (RSE), so there will be… • … software lessons • … science lessons • … lessons about how they interact • All of this is common practice in the open-source world – but not the science world. • This is due solely to differences in experience and training, not neglect or carelessness. • Scientists and RSEs have to work together. Background • The kaiju software uses the magnetohydrodynamic (MHD) equations to model planetary magnetospheres and the heliosphere on a variable-resolution 3D grid. • Consists of a large body of Fortran code with support and analysis code in Python. • Designed to run on High-Performance Computing (HPC) systems such as Pleiades (NASA Ames) (not long for this world…) and Derecho (NCAR). • Developed as closed research software for several years. • But as a NASA DRIVE Center, we (the CGS) wanted to make it widely-available and encourage widespread use. So how do you retro-fit “open-source”? It’s not just putting the code on BitBucket or GitHub (although you do need to do that)! Lesson 1: Bake in version control at the start • If you are not using a DVCS (Distributed Version Control System), you’re doing it wrong. • So teach the team how to use it properly. • Using git for basic tasks is easy. • It’s also easy to shoot yourself in the foot with a tactical nuke if you’re not careful and thoughtful about how you use it. Such as: • Large binary files • 3rd-party code (more on this later) • Forgetting to use and update a .gitignore file • All of these have tripped us up over the past several years. Lesson 2: Use DVCS to make your life easier • It’s for more than just version control! • Use branches to isolate development (and developers). • Only tag and release from a single branch (typically main). • Repository should be available for users to clone and/fork. • Don’t blindly approve PRs. • Keep commits small. • Semantic tags (name-x.y.z) simplify releases and allow easily-recognized tarballs (name-x.y.z.tar.gz) and other package formats, e.g. pip and conda packages. • Mnemonic tags help, but explicit version tags are essential. Lesson 3: Limit access to merge powers • This is important. • “With great power …” – you know the rest. • Even the most well-intended merge can cause problems if done (or not done) in the wrong place, or at the wrong time. Lesson 4: Use an issue tracker • Duh! • Hard to start, takes discipline to maintain. • But for an open-source project, it is absolutely critical, especially when folks start forking your repo. • We are still working on how best to do this for kaiju.