diff --git a/clang/docs/APINotes.rst b/clang/docs/APINotes.rst
new file mode 100644
index 000000000000..4ac4c01cdefb
--- /dev/null
+++ b/clang/docs/APINotes.rst
@@ -0,0 +1,363 @@
+================================================
+API Notes: Annotations Without Modifying Headers
+================================================
+
+**The Problem:** You have headers you want to use, but you also want to add
+extra information to the API. You don't want to put that information in the
+headers themselves --- perhaps because you want to keep them clean for other
+clients, or perhaps because they're from some open source project and you don't
+want to modify them at all.
+
+**Incomplete solution:** Redeclare all the interesting parts of the API in your
+own header and add the attributes you want. Unfortunately, this:
+
+* doesn't work with attributes that must be present on a definition
+* doesn't allow changing the definition in other ways
+* requires your header to be included in any client code to take effect
+
+**Better solution:** Provide a "sidecar" file with the information you want to
+add, and have that automatically get picked up by the module-building logic in
+the compiler.
+
+That's API notes.
+
+API notes use a YAML-based file format. YAML is a format best explained by
+example, so here is a `small example`__ from the compiler test suite of API
+notes for a hypothetical "SomeKit" framework.
+
+__ test/APINotes/Inputs/Frameworks/SomeKit.framework/Headers/SomeKit.apinotes
+
+
+Usage
+=====
+
+API notes files are found relative to the module map that defines a module,
+under the name "SomeKit.apinotes" for a module named "SomeKit". Additionally, a
+file named "SomeKit_private.apinotes" will also be picked up to go with a
+private module map. For bare modules these two files will be in the same
+directory as the corresponding module map; for framework modules, they should
+be placed in the Headers and PrivateHeaders directories, respectively. The
+module map for a private top-level framework module should be placed in the
+PrivateHeaders directory as well, though it does not need an additional
+"_private" suffix on its name.
+
+Clang will search for API notes files next to module maps only when passed the
+``-fapi-notes-modules`` option.
+
+
+Limitations
+===========
+
+- Since they're identified by module name, API notes cannot be used to modify
+  arbitrary textual headers.
+
+
+"Versioned" API Notes
+=====================
+
+Many API notes affect how a C API is imported into Swift. In order to change
+that behavior while still remaining backwards-compatible, API notes can be
+selectively applied based on the Swift compatibility version provided to the
+compiler (e.g. ``-fapi-notes-swift-version=5``). The rule is that an
+explicitly-versioned API note applies to that version *and all earlier
+versions,* and any applicable explicitly-versioned API note takes precedence
+over an unversioned API note.
+
+
+Reference
+=========
+
+An API notes file contains a YAML dictionary with the following top-level
+entries:
+
+:Name:
+
+  The name of the module (the framework name, for frameworks). Note that this
+  is always the name of a top-level module, even within a private API notes
+  file.
+
+  ::
+
+    Name: MyFramework
+
+:Classes, Protocols, Tags, Typedefs, Globals, Enumerators, Functions:
+
+  Arrays of top-level declarations. Each entry in the array must have a
+  'Name' key with its Objective-C name. "Tags" refers to structs, enums, and
+  unions; "Enumerators" refers to enum cases.
+
+  ::
+
+    Classes:
+    - Name: MyController
+      …
+    - Name: MyView
+      …
+
+:SwiftVersions:
+
+  Contains explicit information for backwards compatibility. Each entry in
+  the array contains a 'Version' key, which should be set to '4' for
+  annotations that only apply to Swift 4 mode and earlier. The other entries
+  in this dictionary are the same declaration entries as at the top level:
+  Classes, Protocols, Tags, Typedefs, Globals, Enumerators, and Functions.
+
+  ::
+
+    SwiftVersions:
+    - Version: 4
+      Classes: …
+      Protocols: …
+
+Each entry under 'Classes' and 'Protocols' can contain "Methods" and
+"Properties" arrays, in addition to the attributes described below:
+
+:Methods:
+
+  Identified by 'Selector' and 'MethodKind'; the MethodKind is either
+  "Instance" or "Class".
+
+  ::
+
+    Classes:
+    - Name: UIViewController
+      Methods:
+      - Selector: "presentViewController:animated:"
+        MethodKind: Instance
+        …
+
+:Properties:
+
+  Identified by 'Name' and 'PropertyKind'; the PropertyKind is also either
+  "Instance" or "Class".
+
+  ::
+
+    Classes:
+    - Name: UIView
+      Properties:
+      - Name: subviews
+        PropertyKind: Instance
+        …
+
+Each declaration supports the following annotations (if relevant to that
+declaration kind), all of which are optional:
+
+:SwiftName:
+
+  Equivalent to ``NS_SWIFT_NAME``. For a method, must include the full Swift name
+  with all arguments. Use "_" to omit an argument label.
+
+  ::
+
+    - Selector: "presentViewController:animated:"
+      MethodKind: Instance
+      SwiftName: "present(_:animated:)"
+
+    - Class: NSBundle
+      SwiftName: Bundle
+
+:Availability, AvailabilityMsg:
+
+  A value of "nonswift" is equivalent to ``NS_SWIFT_UNAVAILABLE``. A value of
+  "available" can be used in the "SwiftVersions" section to undo the effect of
+  "nonswift".
+
+  ::
+
+    - Selector: "dealloc"
+      MethodKind: Instance
+      Availability: nonswift
+      AvailabilityMsg: "prefer 'deinit'"
+
+:SwiftPrivate:
+
+  Equivalent to NS_REFINED_FOR_SWIFT.
+
+  ::
+
+    - Name: CGColorEqualToColor
+      SwiftPrivate: true
+
+:Nullability:
+
+  Used for properties and globals. There are four options, identified by their
+  initials:
+
+  - ``Nonnull`` or ``N`` (corresponding to ``_Nonnull``)
+  - ``Optional`` or ``O`` (corresponding to ``_Nullable``)
+  - ``Unspecified`` or ``U`` (corresponding to ``_Null_unspecified``)
+  - ``Scalar`` or ``S`` (deprecated)
+
+  Note that 'Nullability' is overridden by 'Type', even in a "SwiftVersions"
+  section.
+
+  .. note::
+
+    'Nullability' can also be used to describe the argument types of methods
+    and functions, but this usage is deprecated in favor of 'Parameters' (see
+    below).
+
+  ::
+
+    - Name: dataSource
+      Nullability: O
+
+:NullabilityOfRet:
+
+  Used for methods and functions. Describes the nullability of the return type.
+
+  Note that 'NullabilityOfRet' is overridden by 'ResultType', even in a
+  "SwiftVersions" section.
+
+  .. warning::
+
+    Due to a compiler bug, 'NullabilityOfRet' may change nullability of the
+    parameters as well (rdar://30544062). Avoid using it and instead use
+    'ResultType' and specify the return type along with a nullability
+    annotation (see documentation for 'ResultType').
+
+  ::
+
+    - Selector: superclass
+      MethodKind: Class
+      NullabilityOfRet: O
+
+:Type:
+
+  Used for properties and globals. This completely overrides the type of the
+  declaration; it should ideally only be used for Swift backwards
+  compatibility, when existing type information has been made more precise in a
+  header. Prefer 'Nullability' and other annotations when possible.
+
+  We parse the specified type as if it appeared at the location of the
+  declaration whose type is being modified.  Macros are not available and
+  nullability must be applied explicitly (even in an ``NS_ASSUME_NONNULL_BEGIN``
+  section).
+
+  ::
+
+    - Name: delegate
+      PropertyKind: Instance
+      Type: "id"
+
+:ResultType:
+
+  Used for methods and functions. This completely overrides the return type; it
+  should ideally only be used for Swift backwards compatibility, when existing
+  type information has been made more precise in a header.
+
+  We parse the specified type as if it appeared at the location of the
+  declaration whose type is being modified.  Macros are not available and
+  nullability must be applied explicitly (even in an ``NS_ASSUME_NONNULL_BEGIN``
+  section).
+
+  ::
+
+    - Selector: "subviews"
+      MethodKind: Instance
+      ResultType: "NSArray * _Nonnull"
+
+:SwiftImportAsAccessors:
+
+  Used for properties. If true, the property will be exposed in Swift as its
+  accessor methods, rather than as a computed property using ``var``.
+
+  ::
+
+    - Name: currentContext
+      PropertyKind: Class
+      SwiftImportAsAccessors: true
+
+:NSErrorDomain:
+
+  Used for ``NSError`` code enums. The value is the name of the associated
+  domain ``NSString`` constant; an empty string (``""``) means the enum is a
+  normal enum rather than an error code.
+
+  ::
+
+    - Name: MKErrorCode
+      NSErrorDomain: MKErrorDomain
+
+:SwiftWrapper:
+
+  Controls ``NS_STRING_ENUM`` and ``NS_EXTENSIBLE_STRING_ENUM``. There are three
+  options:
+
+  - "struct" (extensible)
+  - "enum"
+  - "none"
+
+  Note that even an "enum" wrapper is still presented as a struct in Swift;
+  it's just a "more enum-like" struct.
+
+  ::
+
+    - Name: AVMediaType
+      SwiftWrapper: none
+
+:EnumKind:
+
+  Has the same effect as ``NS_ENUM`` and ``NS_OPTIONS``. There are four options:
+
+  - "NSEnum" / "CFEnum"
+  - "NSClosedEnum" / "CFClosedEnum"
+  - "NSOptions" / "CFOptions"
+  - "none"
+
+  ::
+
+    - Name: GKPhotoSize
+      EnumKind: none
+
+:Parameters:
+
+  Used for methods and functions. Parameters are identified by a 0-based
+  'Position' and support the 'Nullability', 'NoEscape', and 'Type' keys.
+
+  .. note::
+
+    Using 'Parameters' within a parameter entry to describe the parameters of a
+    block is not implemented. Use 'Type' on the entire parameter instead.
+
+  ::
+
+    - Selector: "isEqual:"
+      MethodKind: Instance
+      Parameters:
+      - Position: 0
+        Nullability: O
+
+:NoEscape:
+
+  Used only for block parameters. Equivalent to ``NS_NOESCAPE``.
+
+  ::
+
+    - Name: dispatch_sync
+      Parameters:
+      - Position: 0
+        NoEscape: true
+
+:SwiftBridge:
+
+  Used for Objective-C class types bridged to Swift value types. An empty
+  string ("") means a type is not bridged. Not supported outside of Apple
+  frameworks (the Swift side of it requires conforming to implementation-detail
+  protocols that are subject to change).
+
+  ::
+
+    - Name: NSIndexSet
+      SwiftBridge: IndexSet
+
+:DesignatedInit:
+
+  Used for init methods. Equivalent to ``NS_DESIGNATED_INITIALIZER``.
+
+  ::
+
+    - Selector: "initWithFrame:"
+      MethodKind: Instance
+      DesignatedInit: true
diff --git a/clang/test/APINotes/Inputs/Frameworks/SomeKit.framework/Headers/SomeKit.apinotes b/clang/test/APINotes/Inputs/Frameworks/SomeKit.framework/Headers/SomeKit.apinotes
new file mode 100644
index 000000000000..ff88fdbaeac8
--- /dev/null
+++ b/clang/test/APINotes/Inputs/Frameworks/SomeKit.framework/Headers/SomeKit.apinotes
@@ -0,0 +1,98 @@
+Name: SomeKit
+Classes:
+  - Name: A
+    Methods:
+      - Selector:        "transform:"
+        MethodKind:      Instance
+        Availability:    none
+        AvailabilityMsg: "anything but this"
+      - Selector: "transform:integer:"
+        MethodKind:      Instance
+        NullabilityOfRet: N
+        Nullability:      [ N, S ]
+      - Selector: "implicitGetOnlyInstance"
+        MethodKind:      Instance
+        Availability:    none
+        AvailabilityMsg: "getter gone"
+      - Selector: "implicitGetOnlyClass"
+        MethodKind:      Class
+        Availability:    none
+        AvailabilityMsg: "getter gone"
+      - Selector: "implicitGetSetInstance"
+        MethodKind:      Instance
+        Availability:    none
+        AvailabilityMsg: "getter gone"
+      - Selector: "implicitGetSetClass"
+        MethodKind:      Class
+        Availability:    none
+        AvailabilityMsg: "getter gone"
+      - Selector: "setImplicitGetSetInstance:"
+        MethodKind:      Instance
+        Availability:    none
+        AvailabilityMsg: "setter gone"
+      - Selector: "setImplicitGetSetClass:"
+        MethodKind:      Class
+        Availability:    none
+        AvailabilityMsg: "setter gone"
+    Properties:
+      - Name: intValue
+        PropertyKind:    Instance
+        Availability: none
+        AvailabilityMsg: "wouldn't work anyway"
+      - Name: nonnullAInstance
+        PropertyKind:    Instance
+        Nullability:     N
+      - Name: nonnullAClass
+        PropertyKind:    Class
+        Nullability:     N
+      - Name: nonnullABoth
+        Nullability:     N
+  - Name: B
+    Availability: none
+    AvailabilityMsg: "just don't"
+  - Name: C
+    Methods:
+      - Selector: "initWithA:"
+        MethodKind: Instance
+        DesignatedInit: true
+  - Name: OverriddenTypes
+    Methods:
+      - Selector: "methodToMangle:second:"
+        MethodKind: Instance
+        ResultType: 'char *'
+        Parameters:
+          - Position: 0
+            Type: 'SOMEKIT_DOUBLE *'
+          - Position: 1
+            Type: 'float *'
+    Properties:
+      - Name: intPropertyToMangle
+        PropertyKind: Instance
+        Type: 'double *'
+Functions:
+  - Name: global_int_fun
+    ResultType: 'char *'
+    Parameters:
+      - Position: 0
+        Type: 'double *'
+      - Position: 1
+        Type: 'float *'
+Globals:
+  - Name: global_int_ptr
+    Type: 'double (*)(int, int)'
+SwiftVersions:
+  - Version: 3.0
+    Classes:
+      - Name: A
+        Methods:
+          - Selector: "transform:integer:"
+            MethodKind:      Instance
+            NullabilityOfRet: O
+            Nullability:      [ O, S ]
+        Properties:
+          - Name: explicitNonnullInstance
+            PropertyKind:    Instance
+            Nullability:     O
+          - Name: explicitNullableInstance
+            PropertyKind:    Instance
+            Nullability:     N
diff --git a/clang/test/APINotes/Inputs/Frameworks/SomeKit.framework/Headers/SomeKit.h b/clang/test/APINotes/Inputs/Frameworks/SomeKit.framework/Headers/SomeKit.h
new file mode 100644
index 000000000000..1a192f5432fd
--- /dev/null
+++ b/clang/test/APINotes/Inputs/Frameworks/SomeKit.framework/Headers/SomeKit.h
@@ -0,0 +1,60 @@
+#ifndef SOMEKIT_H
+#define SOMEKIT_H
+
+__attribute__((objc_root_class))
+@interface A
+-(A*)transform:(A*)input;
+-(A*)transform:(A*)input integer:(int)integer;
+
+@property (nonatomic, readonly, retain) A* someA;
+@property (nonatomic, retain) A* someOtherA;
+
+@property (nonatomic) int intValue;
+@end
+
+@interface B : A
+@end
+
+@interface C : A
+- (instancetype)init;
+- (instancetype)initWithA:(A*)a;
+@end
+
+@interface ProcessInfo : A
++(instancetype)processInfo;
+@end
+
+@interface A(NonNullProperties)
+@property (nonatomic, readwrite, retain) A *nonnullAInstance;
+@property (class, nonatomic, readwrite, retain) A *nonnullAInstance;
+
+@property (nonatomic, readwrite, retain) A *nonnullAClass;
+@property (class, nonatomic, readwrite, retain) A *nonnullAClass;
+
+@property (nonatomic, readwrite, retain) A *nonnullABoth;
+@property (class, nonatomic, readwrite, retain) A *nonnullABoth;
+@end
+
+#import <SomeKit/SomeKitExplicitNullability.h>
+
+extern int *global_int_ptr;
+
+int *global_int_fun(int *ptr, int *ptr2);
+
+#define SOMEKIT_DOUBLE double
+
+__attribute__((objc_root_class))
+@interface OverriddenTypes
+-(int *)methodToMangle:(int *)ptr1 second:(int *)ptr2;
+@property int *intPropertyToMangle;
+@end
+
+@interface A(ImplicitGetterSetters)
+@property (nonatomic, readonly, retain) A *implicitGetOnlyInstance;
+@property (class, nonatomic, readonly, retain) A *implicitGetOnlyClass;
+
+@property (nonatomic, readwrite, retain) A *implicitGetSetInstance;
+@property (class, nonatomic, readwrite, retain) A *implicitGetSetClass;
+@end
+
+#endif
diff --git a/clang/test/APINotes/Inputs/Frameworks/SomeKit.framework/Headers/SomeKitExplicitNullability.h b/clang/test/APINotes/Inputs/Frameworks/SomeKit.framework/Headers/SomeKitExplicitNullability.h
new file mode 100644
index 000000000000..914ab00357fc
--- /dev/null
+++ b/clang/test/APINotes/Inputs/Frameworks/SomeKit.framework/Headers/SomeKitExplicitNullability.h
@@ -0,0 +1,4 @@
+@interface A(ExplicitNullabilityProperties)
+@property (nonatomic, readwrite, retain, nonnull) A *explicitNonnullInstance;
+@property (nonatomic, readwrite, retain, nullable) A *explicitNullableInstance;
+@end
diff --git a/clang/test/APINotes/Inputs/Frameworks/SomeKit.framework/Headers/SomeKit_private.apinotes b/clang/test/APINotes/Inputs/Frameworks/SomeKit.framework/Headers/SomeKit_private.apinotes
new file mode 100644
index 000000000000..aee8c3684dc4
--- /dev/null
+++ b/clang/test/APINotes/Inputs/Frameworks/SomeKit.framework/Headers/SomeKit_private.apinotes
@@ -0,0 +1,15 @@
+Name: SomeKit
+Classes:
+  - Name: A
+    Methods:
+      - Selector: "privateTransform:input:"
+        MethodKind:      Instance
+        NullabilityOfRet: N
+        Nullability:      [ N, S ]
+    Properties:
+      - Name: internalProperty
+        Nullability: N
+Protocols:
+  - Name: InternalProtocol
+    Availability: none
+    AvailabilityMsg: "not for you"