@TRadigk Interested if you have any comments on this PR. Does it look like it resolves your comment from here: #15230 (comment) ?

@projectgus I've checked all changes and fully agree with them. The boot sequence is clearly laid out and to be found on a top level 👍 (which helps to understand that this is not port port specific, but micropython specific). You added a way to recover from soft-bricking for every port allowing it to be found with the search and providing guidance to recover, which I also like very much.
I think this is a great addition to the docs! Thank you! 😎

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 98.57%. Comparing base (97af100) to head (5f0a2a7).

@@           Coverage Diff           @@
##           master   #15956   +/-   ##
=======================================
  Coverage   98.57%   98.57%           
=======================================
  Files         164      164           
  Lines       21335    21335           
=======================================
  Hits        21030    21030           
  Misses        305      305           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

After discussion with @dpgeorge have added a commit which deprecates machine.soft_reset() and recommends sys.exit() instead.

Code size report:

   bare-arm:    +0 +0.000% 
minimal x86:    +0 +0.000% 
   unix x64:    +0 +0.000% standard
      stm32:    +0 +0.000% PYBV10
     mimxrt:    +0 +0.000% TEENSY40
        rp2:    +0 +0.000% RPI_PICO_W
       samd:    +0 +0.000% ADAFRUIT_ITSYBITSY_M4_EXPRESS
  qemu rv32:    +0 +0.000% VIRT_RV32

@andrewleech @dpgeorge Thanks for the great reviews! I've made some edits based on your suggestions, please take a look. (Apologies, I rebased so the "compare" feature in GitHub may show a lot of unrelated edits.)

I have reviewed the changes here and am happy with this PR now.

Except the commit that deprecates machine.soft_reset() in favour of sys.exit(), that needs reconsideration in the light of #15486 (comment)

After discussion with @dpgeorge, machine.soft_reset() is no longer deprecated as the sys.exit() behaviour may change in the future. Updated the relevant commit in this PR to document the current behaviour of sys.exit().

Also rewrote the suggested try/except/finally structure for main.py as the original version locked the user out of the REPL (reset in finally block). This version allows KeyboardInterrupt to drop to a REPL, a safer recommendation...

Also rewrote the suggested try/except/finally structure for main.py as the original version locked the user out of the REPL (reset in finally block). This version allows KeyboardInterrupt to drop to a REPL, a safer recommendation...

It's tricky to recommend something because in production you'd usually want the app to be as robust and secure as possible and hence not allow ctrl-C or anything to stop it, but that contradicts with having a convenient development cycle, eg using mpremote.

Anyway, what you have now is good!