Start adding MarkDown docs for various internals

docs-mini/README-cmake.md

@@ -0,0 +1,59 @@
+= CMake in FlightGear overview =
+
+CMake has evolved considerably over the years; if you're reading external tutorials on it, ensure
+they mention 'modern CMake' since it's very different to the older style.
+
+The top-level CMakeList.txt handles configuration options, finding dependencies, and scanning
+the rest of the source tree. Across the source tree we add executables, includ the main FGFS
+binary but also other helpers and utilities. We also define targets for helper libraries for
+various reasons; for example to build some code with different include paths or flags.
+
+Due to the original code structure, we use some helper functions to collect most of the 
+application sources into two global CMake variables, which are then read and added to the
+main executable target, in `src/Main/CMakeList.txt`. Therefore, many subdirectories have
+a trivial CMakeList.txt which simply calls the helper functions to add its sources:
+
+```
+include(FlightGearComponent)
+
+set(SOURCES
+	foo.cxx
+	bar.cxx
+	)
+
+set(HEADERS
+	foo.hxx
+	bar.hxx
+	)
+    	
+flightgear_component(MyComp "${SOURCES}" "${HEADERS}")
+```
+
+== Configurations ==
+
+Release builds are built with RelWithDebInfo; this is also the most useful configuration for
+development, sicne on Windows, Debug is unusably slow. If trying to optimise performance,
+keep in mind that compiler flags must be manually set for `RelWithDebInfo`; they are _not_
+automatically inherited from `Release`.
+
+
+== Dependencies ==
+
+All dependencies should be handled via an `IMPORTED` target: this ensures that include paths,
+link options, etc specific to the dependency are handled correclty across different platforms.
+
+Depending on the dependency, it may supply a Foo-Config.cmake which defines such a target for
+you automatically. Or there may be an existing `FindFoo.cmake` which does the same. If neither
+of these situations exist, create a custom finder file in `CMakeModules`, following the existing
+examples. 
+
+CMake tracks transitive dependencies correctly, so for example if your new dependency is used
+in SimGear, it will automatically be added to the include / link paths for FlightGear based on
+the SimGear build type.
+
+If you encounter a case where a downstream target is missing an include path or flag for a
+dependency, it typically indicates a bug in your dependency graph. Do _not_ fix it by maanually
+modifying the downstream target's include path or flags. Rather, fix your dependency graph 
+and/or `INTERFACE` exports from your dependency, so that CMake can see the required transitive
+dependencies correctly.
+

docs-mini/README-sentry.md

@@ -0,0 +1,52 @@
+= Sentry.io Cash Reporting =
+
+FlightGear can optionally report crashes and serious errors to Sentry.io. We have a sponsored
+account provided gratis by Sentry; for access to this, ask on the developer list.
+
+== Error conditions ==
+
+If FlightGear crahses, SDentry will automatically submit a report. For non-crash errors,
+we manually submit an exception report. At present this is done whenever we trigger the
+'fatalMessageBox', and in other serious situations. Deciding where is appropriate (or not)
+to report the error to Sentry is a key challenge of the system, since we don't want to
+report user misconfiguration problems, but we do want to detect recurring and
+systematic failures, eg broken aircraft.
+
+In general since we have (almost) unlimited event limits on our sponsored plan, it's 
+better to send errors and filter them on the server side, but this needs to be done 
+with some intelligence; for example we do not (at present) report Nasal runtime
+errors, since this might overload the system.
+
+== Data Protection ==
+
+We explicitly don't include any personal information in the reports, and disable IP address
+collection. Since this makes it hard to cluster reports by user, we instead generate a UUID
+corresponding to a FlightGear installation. This gives us a way to anonymously cluster reports
+by user, without any personal data disclosure.
+
+== Supplementatal Data ==
+
+We record various pieces of configuration state as 'tags': such as the OS, graphics card,
+key settings (eg, is multi-player enabled, which aircraft is being flown) as _tags_ in
+Sentry terminology. This allows grouping of reports by similar tags; for example we can
+identify that a particular crash only occurs with Intel Graphics, or when flying the
+C172.
+
+Additionally we record 'breadcrumbs'; these are included with an error report if one
+is sent, and give an idea of the path of the user through the application, prior to the
+crash. We have breadcrumbs for key events such as the splash-screen completing, the
+user changing position, or scenery being reloaded.
+
+WARN and ALERT level `SG_LOG` messages are currently included as breadcrumbs automatically;
+this means it's important not casually add messages at the levels for non-serious conditions.
+The integration code has a list of commonly ocurring but non-useful messages which are
+skipped from sending; especially some OSG ones related to minor PNG and AC3D data issues.
+
+Adding new tags or breadcrumbs should be done with care, but is generally useful, and
+suggestions in this area are appreciated.
+
+== API ==
+
+All the API is contained in `sentryIntegration.hxx`, inside the `flightgear` namespace. 
+The methods are no-ops if the Sentry SDK was not available at CMake time, and are also
+no-ops if the user has disabled sentry reporting.