add docs for upgrading bundled libs [ci skip] (#7286)

Author: kripken

docs/process.md

@@ -1,8 +1,8 @@
 Release Processes
-=================
+-----------------
 
 Minor version updates (1.X.Y to 1.X.Y+1)
-----------------------------------------
+========================================
 
 When:
 
@@ -26,7 +26,7 @@ How:
 
 
 Major version update (1.X.Y to 1.(X+1).0)
------------------------------------------
+=========================================
 
 When:
 

docs/upgrading-bundled-libs.Markdown

@@ -0,0 +1,26 @@
+
+Upgrading Bundled System Libraries
+==================================
+
+This includes musl, libc++, and others whose source is bundled in our repo
+for simplicity.
+
+To update them,
+
+ * Update the files in `system/` with the new version's files. For example,
+   for musl that means `system/lib/libc/musl` and `system/include/libc`. You
+   need to handle Emscripten's local changes, which are marked with
+   `XXX EMSCRIPTEN` comments, may need to handle merge conflicts there. It is
+   useful to search the git diff for `EMSCRIPTEN` to see those areas.
+ * Update the list of symbols. Those symbols are scanned by the linker in order
+   to know whether to link in a system library or not (so a missing symbol
+   may cause linking to not include something you need). The files are under
+   `system/lib`/ and have the suffix `.symbol`. To generate the new contents,
+   build the system library with the new files, and do something like this
+   for musl:
+   `~/Dev/fastcomp/build/bin/llvm-nm ~/.emscripten_cache/asmjs/libc.bc | sort`
+   and write that to the `.symbol` file. Take a look at the git diff to see
+   if anything looks odd.
+ * Run the test suite to make sure everything works. You can open a PR and let
+   the continuous integration run it for you.
+