Add breaking changes policy (#6585) (#6595)

* Add breaking changes policy

* Add release notes to index

* Fix docs

* Change heading level

* Fix formatting

* Fix formatting

Co-authored-by: Steve Gordon <[email protected]>

Author: github-actions[bot]

.gitignore

@@ -30,7 +30,7 @@ test-results/*
 *.sbr
 *.DotSettings.user
 obj/
-[Rr]elease*/
+[Rr]elease/
 _ReSharper*/
 _NCrunch*/
 [Tt]est[Rr]esult*

docs/index.asciidoc

@@ -3,13 +3,8 @@
 [[elasticsearch-net-reference]]
 = Elasticsearch .NET Client
 
-////
-IMPORTANT NOTE
-==============
-This file has been generated from https://github.com/elastic/elasticsearch-net/tree/master/src/Tests/Tests/index.asciidoc. 
-If you wish to submit a PR for any spelling mistakes, typos or grammatical errors for this file,
-please modify the original csharp file found at the link and submit the PR with that change. Thanks!
-////
+:net-client: Elasticsearch .NET Client
+
 
 include::{asciidoc-dir}/../../shared/attributes.asciidoc[]
 
@@ -35,4 +30,6 @@ include::query-dsl.asciidoc[]
 
 include::aggregations.asciidoc[]
 
-include::redirects.asciidoc[]
+include::redirects.asciidoc[]
+
+include::release-notes/release-notes.asciidoc[]

docs/release-notes/breaking-change-policy.asciidoc

@@ -0,0 +1,30 @@
+[[breaking-changes-policy]]
+== Breaking changes policy
+
+The {net-client} source code is generated from a https://github.com/elastic/elasticsearch-specification[formal specification of the Elasticsearch API]. This API specification is large, and although it is tested against hundreds of Elasticsearch test files, it may have discrepancies with the actual API that result in issues in the {net-client}.
+
+Fixing these discrepancies in the API specification results in code changes in the {net-client}, and some of these changes can require code updates in your applications.
+
+This section explains how these breaking changes are considered for inclusion in {net-client} releases.
+
+[discrete]
+==== Breaking changes in patch releases
+
+Some issues in the API specification are properties that have an incorrect type, such as a `long` that should be a `string`, or a required property that is actually optional. These issues can cause the {net-client} to not work properly or even throw exceptions.
+
+When a specification issue is discovered and resolved, it may require code updates in applications using the {net-client}. Such breaking changes are considered acceptable, _even in patch releases_ (e.g. 7.17.0 -> 7.17.1), as they introduce stability to APIs that may otherwise be unusable.
+
+[discrete]
+==== Breaking changes in minor releases
+
+Along with these bug fixes, the API specification is constantly refined, more precise type definitions are introduced to improve developer comfort and remove ambiguities. The specification of often-used APIs is fairly mature, so these changes happen generally on less often used APIs. These changes can also cause breaking changes requiring code updates which are considered _acceptable in minor releases_ (e.g. 8.0 -> 8.1).
+
+[discrete]
+==== Breaking changes in major releases
+
+Major releases (e.g. 7.x -> 8.x) can include larger refactorings of the API specification and the framework underlying the {net-client}. These refactorings are considered carefully and done only when they unlock new important features or new developments.
+
+[discrete]
+==== Elasticsearch API stability guarantees
+
+All Elasticsearch APIs have stability indicators, which imply potential changes. If an API is `stable` only additional non-breaking changes are added. In case of `experimental` APIs, breaking changes can be introduced any time, which means that these changes, will also be reflected in the {net-client}.

docs/release-notes/release-notes-8.0.0-generated.asciidoc

@@ -2,7 +2,4 @@
 [[release-notes-8.0.0]]
 == Release-Notes 8.0.0
 
-include::release-notes-8.0.0-human.asciidoc[]
-include::release-notes-8.0.0-generated.asciidoc[]
-
-
+Coming soon!

docs/release-notes/release-notes-8.0.0-human.asciidoc

@@ -1,15 +1,6 @@
 [[release-notes]]
 = Release notes
 
-[partintro]
---
-Review important information about 8.0.x releases.
-
-* <<release-notes-8.0.0>>
---
-
-
-
-include::release-notes-8.0.0.asciidoc[]
-
+* <<breaking-changes-policy,Breaking changes policy>>
 
+include::breaking-change-policy.asciidoc[]