625a5f2525117ff4c3e5a73ad73c020af9bdd1f5
markd
  Wed Apr 29 19:45:37 2026 -0700
added README for submodules, currently just htslib

diff --git src/submodules/README.md src/submodules/README.md
new file mode 100644
index 00000000000..4c176dcfd51
--- /dev/null
+++ src/submodules/README.md
@@ -0,0 +1,32 @@
+# submodules
+
+Submodules used by the UCSC Browser source are cloned here.
+`src/makefile` invokes `src/submoduleSetup`, which runs
+`git submodule update --init --recursive` when needed and
+errors out if a stale `src/htslib` directory is still present.
+
+## htslib
+
+Fork of https://github.com/samtools/htslib. The only UCSC patch
+is a CRAM reference existence check that returns a status instead
+of triggering a download. The browser drops a marker file and
+informs the user to check back later; a cron job downloads the
+reference asynchronously.
+
+The remained of UCSC support, include UDC file access, goes through the
+standard htslib interfaces.
+
+Canonical repo: `/data/git/htslib.git` (UCSC internal).
+Mirror: https://github.com/ucscgenomebrowser (htslib repo).
+
+UCSC changes live on branch `ucsc-browser-support`, rebased onto
+each upstream release. The branch point is marked with a tag of
+the form `ucsc-browser-support_<upstream-version>`, e.g.
+`ucsc-browser-support_1.23.1`.
+
+### Updating to a new htslib release
+
+1. In the submodule: fetch upstream, rebase `ucsc-browser-support`
+   onto the new upstream tag.
+2. Tag `ucsc-browser-support_<ver>` and push the branch and tag.
+3. In kent: bump the submodule pointer and commit.