Merge branch 'djensen-add-definition-of-breaking-change' into 'master'

Add definition of "breaking changes"

See merge request gitlab-org/gitlab!52962

doc/api/graphql/index.md

@@ -48,7 +48,7 @@ libraries](https://graphql.org/code/#graphql-clients) to consume the
 API and avoid manual parsing.
 
 Since there's no fixed endpoints and data model, new abilities can be
-added to the API without creating breaking changes. This allows us to
+added to the API without creating [breaking changes](../../development/contributing/#breaking-changes). This allows us to
 have a versionless API as described in [the GraphQL
 documentation](https://graphql.org/learn/best-practices/#versioning).
 

doc/development/contributing/index.md

@@ -181,11 +181,21 @@ reasons for including it.
 `@mention` a maintainer in merge requests that contain:
 
 - More than 500 changes.
-- Any major breaking changes.
+- Any major [breaking changes](#breaking-changes).
 - External libraries.
 
 If you are not sure who to mention, the reviewer will do this for you early in the merge request process.
 
+#### Breaking changes
+
+A "breaking change" is any change that requires users to make a corresponding change to their code, settings, or workflow. "Users" might be humans, API clients, or even code classes that "use" another class. Examples of breaking changes include:
+
+- Removing a user-facing feature without a replacement/workaround.
+- Changing the definition of an existing API (by re-naming query parameters, changing routes, etc.).
+- Removing a public method from a code class.
+
+A breaking change can be considered "major" if it affects many users, or represents a significant change in behavior.
+
 #### Issues workflow
 
 This [documentation](issue_workflow.md) outlines the current issue workflow:

doc/development/contributing/merge_request_workflow.md

@@ -150,7 +150,7 @@ Commit messages should follow the guidelines below, for reasons explained by Chr
 #### Why these standards matter
 
 1. Consistent commit messages that follow these guidelines make the history more readable.
-1. Concise standard commit messages helps to identify breaking changes for a deployment or ~"master:broken" quicker when
+1. Concise standard commit messages helps to identify [breaking changes](index.md#breaking-changes) for a deployment or ~"master:broken" quicker when
    reviewing commits between two points in time.
 
 #### Commit message template