added schema generation doc

Author: Sergey Kanzhelev

EndpointSpecs/schema-generation.md

@@ -0,0 +1,41 @@
+# Application Insights schema
+
+Application Insights schemas for telemetry data located in [Schemas](/Schemas) folder.
+
+
+## Schema and code generation
+
+### Internal endpoint schema
+
+The source of truth for the Application Insights schema is defined in internal endpoint repository. This schema has all public fields as well as planned new fields and deprecated old fields that can be accepted by the endpoint. 
+
+Public schema is generated by removing all fields and data types marked as `deprecated` or `internal` using the `BondSchemaGenerator.exe` tool. See the script in [Tools](/Tools) folder.
+
+### Public schemas
+
+Public schema is located in Application Insights [home](github.com/microsoft/applicationinsights-home) repository. Every SDK generating code from schema keeps it's own copy of schemas. Local copy is stored to ensure consistency between the code and schema this code was generated from. See [dotnet](https://github.com/Microsoft/ApplicationInsights-dotnet/tree/develop/Schema/PublicSchema) repository for example. [Script](https://github.com/Microsoft/ApplicationInsights-dotnet/blob/develop/Schema/generateSchema.ps1) in corresponding repository copy schemas from home repo and generate code.
+
+### Code generation
+
+One of requirements for Application Insights SDK is to minimize the number of dependencies. SDKs do not take dependency on Microsoft Bond packages. Custom tool `BondSchemaGenerator.exe` is used to generate code.
+
+Tools has different level of support for different languages. For C#, tool generate only data structures. 
+
+Another requirement for SDK was minimization of public surface APIs changes. Thus for C# public surface API is manually written code. All generated data classes are part of internal implementation.
+
+### Process of code generation
+
+Internal only:
+
+1. Update schema in internal endpoint repository. 
+2. Generate endpoint code by running scripts in internal endpoint repository. Send PR and ensure schema update is deployed to production. 
+
+Public schemas:
+
+3. In home repository. Run [generateSchema.ps1](https://github.com/Microsoft/ApplicationInsights-dotnet/blob/develop/Schema/generateSchema.ps1). Send PR and ensure it is merged to master.
+
+For .NET:
+
+4. In dotnet repository run [generateSchema.ps1](https://github.com/Microsoft/ApplicationInsights-dotnet/blob/develop/Schema/generateSchema.ps1). Send PR and ensure it is merged to master.
+5. Update public surface API to utilize new fields or expose other schema changes. Follow the standard [contribution process](https://github.com/Microsoft/ApplicationInsights-dotnet/blob/develop/.github/CONTRIBUTING.md) since any change in public API needs to be reviewed.
+6. Update schemas and code in dotnet-server repository [generateSchema.ps1](https://github.com/Microsoft/ApplicationInsights-dotnet-server/blob/develop/Schema/generateSchema.ps1)