Add a safety net to install_openrvdas.sh, then reduce its top-level sprawl

Open
#638 3 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
25/100
Issue type
Refactor
Clarity
Mostly clear
Activity status
Active
Tech stack
bash, github-actions, shell
Domain
ci-cd, devops

Research direction

Start with utils/install_openrvdas.sh, the CI workflow files under .github/workflows, and INSTALL.md, which explains why the installer must stay a single file. Phase 1 covers a shellcheck baseline, a bash -n check on a MacOS runner, and removal of the dead blocks near lines 675-686 and 826-846. Phase 2 extracts the top-level flow into main() with gather_answers and run_install. Done means CI passes on Linux and MacOS, the dead code is gone, and the installer's behavior is unchanged.

Written by the indexing model from the issue text.

Description

Summary

utils/install_openrvdas.sh is the highest-churn file in the repository and has no test, lint, or CI coverage of any kind. This proposes a phased plan: add the safety net first, then make one bounded structural change. No behavior change is intended at any point.

Why now

Size 2,656 lines (1,733 non-comment)
Growth 1,584 at v2.3.0 (Feb 2026) → 2,460 at v2.6.1 → 2,656 today — +68% in seven months
Structure 28 functions, followed by 650 lines of top-level imperative flow
Churn 31 of 117 commits on dev in 2026 touched this file — 27%, more than any other
Coupling 35 $OS_TYPE comparisons; 11 functions carry an "Expect the following shell variables" header, i.e. globals are the calling convention
Hygiene 58 unquoted test expressions; several dead commented-out blocks
Coverage None. No test references it, no CI job runs it, nothing lints it

Two defects in the last month illustrate the gap:

  • #615 — setup_ufw was defined twice (a merge artifact). It shipped to users and needed a filed issue to be noticed. A linter catches this on the commit that introduces it.
  • #629 / PR #630 — the venv-activation snippet could not be written as a heredoc, because the bash 3.2 that MacOS ships cannot parse a heredoc containing ;; inside a command substitution. It parses fine on bash 4+. This was caught only because the change happened to be authored on a Mac; a Linux-authored equivalent would have passed review and broken every MacOS install.

Constraint: this has to stay one file

The installer is fetched standalone by curl and run before the repository exists on disk (see INSTALL.md). Splitting it into sourced modules is therefore not available — there is nothing to source. Any restructuring has to stay within the single file.

Phase 1 — safety net (no behavior change, no runtime risk)

  • Add shellcheck to CI. Catches duplicate function definitions (#615) automatically, plus the unquoted-expansion class. Expect a large initial finding count; baseline it and ratchet down rather than fixing everything in one PR.
  • Add bash -n on a MacOS runner as well as Linux. GitHub's MacOS runners ship bash 3.2 — the version with the heredoc limitation above. This is the check that would have caught the #629 case, and nothing currently protects against it. Small matrix addition to a workflow.
  • Remove dead commented-out code. Two clearly dead blocks: a SQLite version check at ~675-686 and a venv-backup / python-path-probe block at ~826-846. (The commented scutil lines at ~393-395 are a different case — they document a deliberate non-action next to an active echo Not changing hostname on MacOS, and are better kept with a clarifying comment than deleted.)

Phase 1 is independently valuable and should land before anything below.

Phase 2 — reduce top-level sprawl (only once Phase 1 is stable)

  • Extract the 650-line top-level flow into main(), split into two explicit phases. The tail is really gather answers (~2009-2270) followed by execute (~2400-2656), but the boundary is implicit, the ordering dependency between them is undocumented, and both sit ~1,900 lines below the functions they call. A gather_answers / run_install split makes the phase boundary explicit and keeps everything in one file.

Explicitly out of scope

  • Collapsing the 35 $OS_TYPE branches into a dispatch table. It reads as duplication, but the branches differ in substance, and the abstraction would hide precisely the platform-specific behavior most likely to be wrong.
  • Splitting into multiple sourced files — ruled out by the distribution model above.
  • Any change to what the installer actually does.

Risk

This is the highest-consequence file in the repo: the first thing every user runs, where a regression means nobody can install anything. It cannot be meaningfully verified without a VM matrix across MacOS, Ubuntu, RHEL and AlmaLinux. That argues for doing Phase 1 thoroughly and being conservative about Phase 2 — not for leaving the file alone, since at 27% churn it is being modified constantly regardless, currently without a net.

Dominant language
Python
Stars
57
Forks
30
Avg merge
3h 14m
Merged PRs (30d)
56

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from OceanDataTools/openrvdas

All issues in OceanDataTools/openrvdas

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.