[krankthat]

Just like git tags, release notes, makefiles, etc ... Documentation is one of those things that needs to be updated as part of a new release.

[Zalastax]

Yes, it could have been handled better. I guess you need to consider whether it's best to let newcomers in on the v4 goodness or to avoid aliating users of v3. The pragmatic approach is to at least mention somewhere that v3 users should wait on upgrading.