+
+Working With Submodules
+=======================
+
+Mono references several external git submodules, for example
+a fork of Microsoft's reference source code that has been altered
+to be suitable for use with the Mono runtime.
+
+This section describes how to use it.
+
+An initial clone should be done recursively so all submodules will also be
+cloned in a single pass:
+
+ $ git clone --recursive git@github.com:mono/mono
+
+Once cloned, submodules can be updated to pull down the latest changes.
+This can also be done after an initial non-recursive clone:
+
+ $ git submodule update --init --recursive
+
+To pull external changes into a submodule:
+
+ $ cd <submodule>
+ $ git pull origin <branch>
+ $ cd <top-level>
+ $ git add <submodule>
+ $ git commit
+
+By default, submodules are detached because they point to a specific commit.
+Use `git checkout` to move back to a branch before making changes:
+
+ $ cd <submodule>
+ $ git checkout <branch>
+ # work as normal; the submodule is a normal repo
+ $ git commit/push new changes to the repo (submodule)
+
+ $ cd <top-level>
+ $ git add <submodule> # this will record the new commits to the submodule
+ $ git commit
+
+To switch the repo of a submodule (this should not be a common or normal thing
+to do at all), first edit `.gitmodules` to point to the new location, then:
+
+ $ git submodule sync -- <path of the submodule>
+ $ git submodule update --recursive
+ $ git checkout <desired new hash or branch>
+
+The desired output diff is a change in `.gitmodules` to reflect the
+change in the remote URL, and a change in /<submodule> where you see
+the desired change in the commit hash.
+
+License
+=======
+
+See the LICENSE file for licensing information, and the PATENTS.TXT
+file for information about Microsoft's patent grant.
+
+Mono Trademark Use Policy
+=========================
+
+The use of trademarks and logos for Mono can be found [here] (http://www.dotnetfoundation.org/legal/mono-tm).
+
+Maintaining the Class Library Solution Files
+============================================
+
+Mono now ships with a solution file that can be used to build the
+assemblies from an IDE. Either by opening the topmost `net_4_x.sln`
+file, or to by loading one of the individual `csproj` files located in
+each directory.
+
+These are maintained by extracting the configuration information from
+our Makefiles, which as of May 2016 remain the canonical location for
+configuration information.
+
+When changes are made to the Makefiles, a user would need to run the
+following command to re-generate the solution files at the top level:
+
+ $ make update-solution-files
+