From 9d73a52f1fb48f220f430f2c203f116274a1385d Mon Sep 17 00:00:00 2001
From: Alex Gaynor <alex.gaynor@gmail.com>
Date: Sat, 10 Oct 2020 21:12:47 -0400
Subject: [PATCH] Improved documentation

---
 CHANGELOG.md           |  7 +++++++
 guide/src/migration.md | 16 ++++++++++++++++
 src/marshal.rs         |  2 ++
 src/pyclass.rs         |  2 +-
 4 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 52a4d7b23c1..d2b061dacd8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,13 @@ PyO3 versions, please see the [migration guide](https://pyo3.rs/master/migration
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+### Added
+- Add support for building for CPython limited API. [#1152](https://github.com/PyO3/pyo3/pull/1152)
+
+### Changed
+- Adding support for the CPython limited API had a number of implimplications for the rest of pyo3. See the migration guide for full details.
+
 ## [Unreleased]
 ### Added
 - Add support for keyword-only arguments without default values in `#[pyfunction]`. [#1209](https://github.com/PyO3/pyo3/pull/1209)
diff --git a/guide/src/migration.md b/guide/src/migration.md
index 535bc97a32a..3f66b9abf99 100644
--- a/guide/src/migration.md
+++ b/guide/src/migration.md
@@ -3,6 +3,22 @@
 This guide can help you upgrade code through breaking changes from one PyO3 version to the next.
 For a detailed list of all changes, see the [CHANGELOG](changelog.md).
 
+## from 0.12.* to 0.13
+
+### Limited API
+
+In PyO3 `0.13` support was added for compiling against the CPython limited API. This had a number of implications for _all_ PyO3 users, described here.
+
+The largest of these is that all types created from PyO3 are what CPython calls "heap" types. The specific implications of this are:
+
+- If you wish to subclass one of these types _from Rust_ you must mark it `#[pyclass(subclass)]`, as you would if you wished to allow subclassing it from Python code.
+- Type objects are now mutable - Python code can set attributes on them.
+- `__module__` on types without `#[pyclass(module="mymodule")]` no longer returns `builtins`, it now raises `AttributeError`.
+
+In addition,
+
+- The `name()` method on `PyType` now returns a `PyResult`.
+
 ## from 0.11.* to 0.12
 
 ### `PyErr` has been reworked
diff --git a/src/marshal.rs b/src/marshal.rs
index f8bcb6a4ce7..342274189c8 100644
--- a/src/marshal.rs
+++ b/src/marshal.rs
@@ -1,4 +1,6 @@
 #![cfg(not(Py_LIMITED_API))]
+//! Support for the Python `marshal` format. Not supported in limited API
+//! builds.
 
 use crate::ffi;
 use crate::types::{PyAny, PyBytes};
diff --git a/src/pyclass.rs b/src/pyclass.rs
index c3fe0231258..b831b45d318 100644
--- a/src/pyclass.rs
+++ b/src/pyclass.rs
@@ -258,7 +258,7 @@ fn tp_init_additional<T: PyClass>(type_object: *mut ffi::PyTypeObject) {
     // except for that it does and we have tests.
 
     // Running this causes PyPy to segfault.
-    #[cfg(not(PyPy))]
+    #[cfg(all(not(PyPy)), not(Py_3_10))]
     if T::DESCRIPTION != "\0" {
         unsafe {
             // Until CPython 3.10, tp_doc was treated specially for heap-types,