Problem this feature will solve
README.md still dedicates a top-level line to the factory_girl migration path:
Transitioning from factory_girl? Check out the [upgrade guide](https://github.com/thoughtbot/factory_bot/blob/v4.9.0/UPGRADE_FROM_FACTORY_GIRL.md).
The rename shipped in 4.8.2 on October 20, 2017 (per NEWS.md), so this
notice is approaching nine years old. It sits in the first screen of the README,
within the first four paragraphs, above the "Documentation" and "Install"
sections, while addressing an audience that has largely completed the
transition by now.
For a rough sense of scale, RubyGems download volume over the last 30 days
(2026-07-31 to 2026-08-29, via bestgems.org):
| gem |
30-day downloads |
avg/day |
factory_bot |
5,719,493 |
190,649 |
factory_girl |
161,586 |
5,386 |
factory_girl accounts for roughly 2.8% of the combined volume. This is an
imperfect proxy. it measures residual installs rather than active migration,
and some share of it is presumably CI re-downloads from projects that have no
intention of migrating at all, but it does suggest the population this line
serves is now a small minority of readers.
Desired solution
Remove the line from README.md, and relocate the pointer to NAME.md, where
the rename is already documented:
The name "Factory Girl" was confusing to some developers who encountered this
library, and offensive or problematic to others. In October 2017 we
renamed the library to "Factory Bot".
If you are still upgrading from factory_girl, see the
upgrade guide.
README.md:10 already links to NAME.md ("Interested in the history of the
project name?"), so the guide stays reachable in one hop for anyone who needs it,
and the README reclaims a line for content relevant to today's users.
Worth noting: NAME.md and NEWS.md reference factory_girl for good reason and
this issue does not propose touching them. Nothing about the project's naming
history is being erased, only the README's framing of a nine-year-old migration
as front-page information.
Alternatives considered
- Remove the line outright, without relocating it. Simpler, but the README is
currently the only place in this repository that links to
UPGRADE_FROM_FACTORY_GIRL.md, I checked docs/src/ and the guide is not
referenced anywhere in the book. Removing the line without a new home would
make the guide effectively undiscoverable from the docs.
- Leave it as is. It costs one line, and the link does still resolve. The
counterargument is that README space is finite, and this line currently outranks
the "Documentation" and "Install" sections that most readers actually came for.
- Wait for a broader README restructure. Reasonable if one is planned; this
change is small enough to stand alone or to be folded into a larger pass.
Additional context
The link target itself is healthy, UPGRADE_FROM_FACTORY_GIRL.md at the
v4.9.0 tag returns 200. so this is a question of placement, not a broken link.
I'm happy to open a PR for this if the direction sounds right. I'd also
understand if maintainers prefer to keep the notice; the rename was a
deliberate, well-communicated decision and I don't want to imply the migration
path should become harder to find.
Problem this feature will solve
README.mdstill dedicates a top-level line to the factory_girl migration path:README.md:12The rename shipped in 4.8.2 on October 20, 2017 (per
NEWS.md), so thisnotice is approaching nine years old. It sits in the first screen of the README,
within the first four paragraphs, above the "Documentation" and "Install"
sections, while addressing an audience that has largely completed the
transition by now.
For a rough sense of scale, RubyGems download volume over the last 30 days
(2026-07-31 to 2026-08-29, via bestgems.org):
factory_botfactory_girlfactory_girl accounts for roughly 2.8% of the combined volume. This is an
imperfect proxy. it measures residual installs rather than active migration,
and some share of it is presumably CI re-downloads from projects that have no
intention of migrating at all, but it does suggest the population this line
serves is now a small minority of readers.
Desired solution
Remove the line from
README.md, and relocate the pointer toNAME.md, wherethe rename is already documented:
README.md:10already links toNAME.md("Interested in the history of theproject name?"), so the guide stays reachable in one hop for anyone who needs it,
and the README reclaims a line for content relevant to today's users.
Worth noting:
NAME.mdandNEWS.mdreference factory_girl for good reason andthis issue does not propose touching them. Nothing about the project's naming
history is being erased, only the README's framing of a nine-year-old migration
as front-page information.
Alternatives considered
currently the only place in this repository that links to
UPGRADE_FROM_FACTORY_GIRL.md, I checkeddocs/src/and the guide is notreferenced anywhere in the book. Removing the line without a new home would
make the guide effectively undiscoverable from the docs.
counterargument is that README space is finite, and this line currently outranks
the "Documentation" and "Install" sections that most readers actually came for.
change is small enough to stand alone or to be folded into a larger pass.
Additional context
The link target itself is healthy,
UPGRADE_FROM_FACTORY_GIRL.mdat thev4.9.0tag returns 200. so this is a question of placement, not a broken link.I'm happy to open a PR for this if the direction sounds right. I'd also
understand if maintainers prefer to keep the notice; the rename was a
deliberate, well-communicated decision and I don't want to imply the migration
path should become harder to find.