id	summary	reporter	owner	description	type	status	component	version	severity	resolution	keywords	cc	stage	has_patch	needs_docs	needs_tests	needs_better_patch	easy	ui_ux
29513	Make TransactionTestCase.multi_db documentation more discoverable.	Adam Johnson	nobody	"I had a pull request that took me two years to resolve (okay, I deferred it quite a lot): https://github.com/adamchainz/django-mysql/pull/278 . This was adding `pytest-randomly` to my project, which randomly sorts the tests and exposes test interdependence. It turned out the failure was due to interdependence between tests that touched a secondary database, with the `TestCase` classes not resetting the secondary database, because `multi_db=True` was missing from such `TestCase`s to get the secondary DB wiped between tests.

Part of the trouble debugging this was that `multi_db` is not easy to find:

* The page on multiple databases doesn't mention or link to testing considerations at all: https://docs.djangoproject.com/en/2.0/topics/db/multi-db/
* The 'test database' section of 'writing and running tests' *does* mention and link to 'advanced multi-db testing topics' : https://docs.djangoproject.com/en/2.0/topics/testing/overview/#the-test-database -> https://docs.djangoproject.com/en/2.0/topics/testing/advanced/#topics-testing-advanced-multidb . However the linked section, ""Tests and multiple databases"", doesn't mention `multi_db` - it's only in the ""Advanced features of TransactionTestCase"" section - and I'd argue it's not an advanced feature but a basic one, even a risk that you'll end up taking 2 years to debug an issue :)
* When `multi_db` is mentioned, it's only in the context of `TransactionTestCase` . `TestCase` isn't mentioned, which yes does inherit from `TransactionTestCase`, but it also has more behaviour, in the scope of class-level `atomic()`s that also obey the `multi_db` flag

I think we should fix the docs for these problems 🎉.

Secondarily, the feature is confusing and I'd flip the default of the flag to `True` and allow setting it to `False` as an optimization - but this is a much bigger change."	Cleanup/optimization	closed	Documentation	dev	Normal	fixed			Accepted	0	0	0	0	0	0