doc: Split out and expand on updating notes

Expands on instructions for updating the code when upstream changes.
Also renaming with the '.md' extension for things that understand
Markdown.

3 files changed, 102 insertions, 45 deletions

diff --git a/README b/README
index cc76fed..96dc92f 100644
--- a/README
+++ b/README
@@ -1,45 +1 @@
-About
-=====
-
-This is meant to be a more Linux packaging friendly copy of the AudioProcessing
-module from the WebRTC[1][2] project. The ideal case is that we make no changes to
-the code to make tracking upstream code easy.
-
-This package currently only includes the AudioProcessing bits, but I am very
-open to collaborating with other projects that wish to distribute other bits of
-the code and hopefully eventually have a single point of packaging all the
-WebRTC code to help people reuse the code and avoid keeping private copies in
-several different projects.
-
-[1] http://code.google.com/p/webrtc/
-[2] https://chromium.googlesource.com/external/webrtc/trunk/webrtc.git
-
-Feedback
-========
-
-Patches, suggestions welcome. You can send them to the PulseAudio mailing
-list[2] or to me at the address below.
-
--- Arun Raghavan <mail@arunraghavan.net>
-
-[3] http://lists.freedesktop.org/mailman/listinfo/pulseaudio-discuss
-
-Notes
-=====
-
-Assembling some quick notes on maintaining this tree vs. the original WebRTC
-project source code.
-
-1. Running meld on a pristine tree's webrtc/ vs. the same directory in the
-   Chromium third_party/webrtc/should produce a fairly easy-to-parse set of
-   differences that can be merged. I've kept the test code out for now, but
-   this might get merged in the future. The .gn files are included to make
-   allow tracking changes to the build system easier.
-
-2. Some files need to be patch to avoid pulling in the gtest framework. This
-   should ideally be pushed upstream in some way so we're able to just pull
-   in what we need without changing anything.
-
-3. It might be nice to try LTO on the library. We build a lot of code as part
-   of the main AudioProcessing module deps, and it's possible that this could
-   provide significant space savings.
+See README.md
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..03de756
--- /dev/null
+++ b/README.md
@@ -0,0 +1,36 @@
+About
+=====
+
+This is meant to be a more Linux packaging friendly copy of the AudioProcessing
+module from the WebRTC[1][2] project. The ideal case is that we make no changes to
+the code to make tracking upstream code easy.
+
+This package currently only includes the AudioProcessing bits, but I am very
+open to collaborating with other projects that wish to distribute other bits of
+the code and hopefully eventually have a single point of packaging all the
+WebRTC code to help people reuse the code and avoid keeping private copies in
+several different projects.
+
+[1] http://code.google.com/p/webrtc/
+[2] https://chromium.googlesource.com/external/webrtc/trunk/webrtc.git
+
+Feedback
+========
+
+Patches, suggestions welcome. You can send them to the PulseAudio mailing
+list[2] or to me at the address below.
+
+-- Arun Raghavan <mail@arunraghavan.net>
+
+[3] http://lists.freedesktop.org/mailman/listinfo/pulseaudio-discuss
+
+Notes
+====
+
+1. Some files need to be patch to avoid pulling in the gtest framework. This
+   should ideally be pushed upstream in some way so we're able to just pull
+   in what we need without changing anything.
+
+2. It might be nice to try LTO on the library. We build a lot of code as part
+   of the main AudioProcessing module deps, and it's possible that this could
+   provide significant space savings.
diff --git a/UPDATING.md b/UPDATING.md
new file mode 100644
index 0000000..581ad07
--- /dev/null
+++ b/UPDATING.md
@@ -0,0 +1,65 @@
+Updating
+=====
+
+Assembling some quick notes on maintaining this tree vs. the upstream WebRTC
+project source code.
+
+1. The code is currently synced agains whatever revision of the upstream
+   webrtc git repository Chromium uses.
+
+2. Instructions on checking out the Chromium tree are on the
+   [Chromium site][get-chromium].
+
+3. [Meld][meld] is a great tool for diffing two directories. Start by running
+   it on ```webrtc-audio-processing/webrtc``` and
+   ```chromium/third_party/webrtc```.
+
+   * For each directory in the ```webrtc-audio-processing``` tree, go over the
+     corresponding code in the ```chromium``` tree.
+
+   * Examine changed files, and pick any new changes. A small number of files
+     in the ```webrtc-audio-processing``` tree have been changed by hand, make
+     sure that those are not overwritten.
+
+   * unittest files have been left out since they are not built or used.
+
+   * BUILD.gn files have been copied to keep track of changes to the build
+     system upstreama.
+
+   * Arch-specific files usually have special handling in the corresponding
+     Makefile.am.
+
+4. Once everything has been copied and updated, everything needs to be built.
+   Missing dependencies (files that were not copied, or new modules that are
+   being depended on) will first turn up here.
+
+   * Copy new deps as needed, leaving out testing-only dependencies insofar as
+     this is possible.
+
+5. ```webrtc/modules/audio_processing/include/audio_processing.h``` is the main
+   include file, so look for API changes here.
+
+   * The current policy is that we mirror upstream API as-is.
+
+   * Update configure.ac with the appropriate version info  based on how the
+     code has changed. Details on how to do this are included in the
+     [libtool documentation][libtool-version-info].
+
+5. Build PulseAudio (and/or any other dependent projects) against the new code.
+   The easy way to do this is via a prefixed install.
+
+   * Run ```configure``` webrtc-audio-processing with
+     ```--prefix=/some/local/path```, then do a ```make``` and
+     ```make install```.
+
+   * Run ```configure``` on PulseAudio with
+     ```PKG_CONFIG_PATH=/some/local/path/lib/pkgconfig```, which will cause the
+     build to pick up the prefixed install. Then do a ```make```, run the built
+     PulseAudio, and load ```module-echo-cancel``` to make sure it loads fine.
+
+   * Run some test streams through the canceller to make sure it is working
+     fine.
+
+[get-chromium]: http://dev.chromium.org/developers/how-tos/get-the-code
+[meld]: http://meldmerge.org/
+[libtool-version-info]: https://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html