The migration documentation is something distro maintainers read, but it's humanly impossible for an user to read all such documentation on every of several thousand packages on a dist-upgrade.

If secring.gpg can't be processed, then --delete-secret-key must at least detect that file's presence and issue a warning, preferably proposing its deletion. Leaving a secret key there, hidden from user-facing interfaces, is a quite critical issue.

It is there for a purpose. If the distros want to enforce a certain policy, they can do that. But we can't do that.
Sure, we could print a warning note. But then we would need to print a lot of warning notes all over the place to the effect that nobody will care about that and ask for an option to silence them.

Note that --delete-secret-key in gpg 1 does not wipe out the key from your disk either; software can't do proper OPSEC. If you care about your key so much, then use a hardware token - you can physically destroy it (you can also do that with a disk of course ;-).

99.9% users will upgrade to gpg2.1 once and never think about downgrading. On Debian for example, to get gpg 1 or 2.0 back, you'd need to rollback the whole dist-upgrade which is so tricky (and officially unsupported) that restoring the whole system from a backup is the only realistic option. Thus, offering to delete secring.gpg on key deletion wouldn't be obnoxious at all. Secret key deletion already asks a number of questions, one more wouldn't be bad. I guess deleting secring.gpg when the passphrase is being changed would be a good idea, too.

As for wiping the disk: on modern HDD, even a single overwrite with zeroes kills almost any means of recovery (as opposed to HDDs from three decades ago), multiple passes kill even that theoretical possibility. Yeah, on CoW filesystems like btrfs wiping is more tricky, but tricky doesn't mean it can't be done right. As for sector remapping -- most admins will tell you that even a single Reallocated_Sector_Ct is grounds for immediately replacing that disk. With SSDs, things are far more complex. Working TRIM goes a long way here. It's still basically impossible to ensure you have physically wiped the key, but easy to know the key is very likely to have been wiped. Forensics people will tell you that SSD internals are so non-standard that about anything beyond the ATA interface lies in the "send to manufacturer" land, thus it should be safe against regular law enforcement or airport goons. This is not good enough for high-profile cases, but the likelihood that, given enough time for the firmware to act and perhaps some extra filesystem churn, the block in question has been erased is so high that it's reasonable to skip physically replacing the disk.

But why would an attacker bother decapping SSD chips if they can just copy secring.gpg?

As said that is a distro thing and nothing we, as upstream authors, will decide for those who build gnupg on their own. Reading README and following migration instructions is a MUST for everyone installing a new version of a software.

If you have a suggestion to improve the documentation, you are welcome to post it here.