From 3ce16edbe29986446849e023fb95a35976366cf2 Mon Sep 17 00:00:00 2001
From: Matthias <Maddosaurus@users.noreply.github.com>
Date: Tue, 1 Oct 2019 16:51:37 +0200
Subject: [PATCH] Extend dataclass doc (#848)

* Add note detailing dataclass vs BaseModel usage

* Add changes rst describing the change
---
 changes/710-maddosaurus.rst | 1 +
 docs/index.rst              | 7 +++++++
 2 files changed, 8 insertions(+)
 create mode 100644 changes/710-maddosaurus.rst

diff --git a/changes/710-maddosaurus.rst b/changes/710-maddosaurus.rst
new file mode 100644
index 0000000..3ba98d4
--- /dev/null
+++ b/changes/710-maddosaurus.rst
@@ -0,0 +1 @@
+Update documentation to specify the use of ``pydantic.dataclasses.dataclass`` and subclassing ``pydantic.BaseModel``.
diff --git a/docs/index.rst b/docs/index.rst
index 2f4302e..dd07f19 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -136,6 +136,13 @@ Dataclasses work in python 3.6 using the `dataclasses backport package <https://
 
 (This script is complete, it should run "as is")
 
+.. note::
+
+   Keep in mind that ``pydantic.dataclasses.dataclass`` is a drop in replacement for ``dataclasses.dataclass``
+   with validation, not a repacement for ``pydantic.BaseModel``. There are cases where subclassing
+   ``pydantic.BaseModel`` is the better choice. For more information and disucssion see
+   `samuelcolvin/pydantic#6239 <https://github.com/samuelcolvin/pydantic/issues/710>`_.
+
 You can use all the standard pydantic field types and the resulting dataclass will be identical to the one
 created by the standard library ``dataclass`` decorator.