From 877667a1c60dafe2b9c2db20604a9578e7fe897e 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           |  8 ++++++++
 guide/src/migration.md | 12 ++++++++++++
 src/marshal.rs         |  2 ++
 src/pyclass.rs         |  2 +-
 4 files changed, 23 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 52a4d7b2..ae7a2b32 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,14 @@ 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. This required a few minor changes to runtime behaviour of of pyo3 `#[pyclass]` types. See the migration guide for full details. [#1152](https://github.com/PyO3/pyo3/pull/1152)
+
+### Changed
+- Change return type `PyType::name()` from `Cow<str>` to `PyResult<&str>`. [#1152](https://github.com/PyO3/pyo3/pull/1152)
+- `#[pyclass(subclass)]` is now required for subclassing from Rust (was previously just required for subclassing from Python). [#1152](https://github.com/PyO3/pyo3/pull/1152)
+
 ## [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 535bc97a..dea3319e 100644
--- a/guide/src/migration.md
+++ b/guide/src/migration.md
@@ -3,6 +3,18 @@
 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
+
+### Runtime changes to support the CPython 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`.
+
 ## from 0.11.* to 0.12
 
 ### `PyErr` has been reworked
diff --git a/src/marshal.rs b/src/marshal.rs
index f8bcb6a4..34227418 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 c3fe0231..e7f68cd8 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,