[Documentation]: absent documentation about v4
Jorropo opened this issue · comments
There are no proper release notes for v4.0.0
It's not on the readme:
Badger v1.0 was released in Nov 2017, and the latest version that is data-compatible with v1.0 is v1.6.0.
Badger v2.0 was released in Nov 2019 with a new storage format which won't be compatible with all of the v1.x. Badger v2.0 supports compression, encryption and uses a cache to speed up lookup.
Badger v3.0 was released in January 2021. This release improves compaction performance.
Please consult the Changelog for more detailed information on releases.
For more details on our version naming schema please read Choosing a version.
it's not in the changelog
https://github.com/dgraph-io/badger/blob/master/CHANGELOG.md
it's not in the "choosing a version"
https://github.com/dgraph-io/badger#choosing-a-version
v4.0.0 is missing
even assuming github's release tab is now the source of truth, v4.0.0 is missing from https://github.com/dgraph-io/badger/releases/
It is unclear if v4.0.1 shows difference between v4.0.1 or prior v3 version.
I understand v4.0.0 is redacted but I think the github release should still exists and have a big bold "DO NOT USE THIS RELEASE" statement to capture history.
I wasn't able to find a rational about v4
Was the on disk format changed ?
Why are the reasons this forked out of v3 ?
What are the future implications for supported versions ?
Will a v5 happen soon and require me to migrate all of my data if I want to update ?
Most of theses questions could be solved by looking at the code, but I don't know badger's codebase and I'm not sure I would pickup all the subtleties correctly.
After some searching I was able to find 31b7588:
Changelog should reflect that we are switching to SemVer. This requires moving to a new major version. We also update all import paths in Badger.
But the conflicting information in the readme is still very meh.
Looks like you are still using the master branch. Checkout the new main branch (master has been deprecated, main is now the default). You'll find all the relevant information in the README. We also post releases on Github with some additional information: https://github.com/dgraph-io/badger/releases
Regarding Badger v4.0.0, the tag still exists in the repository, so you can audit it / go get that version if you wish, but that it will fail to build due to the bug mentioned in the release notes.
The main reason we moved to v4 is because we wanted to move away from CalVer.
Will a v5 happen soon and require me to migrate all of my data if I want to update ?
We are actively developing Badger but a v5 release is not planned in the near term.
@joshua-goldstein I don't see what you mean, I'm on the default branch
which is main, and I don't see a v4 mention
CTRL + Fing v4 on the README only finds this text which mentions v3 but then show example with v4 (that smell strongly like sed replaced import paths matched this)
Hmm I see one source of confusion: the link to the README still uses master in the url. I opened #2011 to fix that. From the changelog (and release notes):
v4.0.0
This release fixes a bug in the maxHeaderSize parameter that could lead to panics. We introduce an external magic number to keep track of external dependencies. We bump up the minimum required Go version to 1.19. No changes were made to the format of data on disk. This is a major release because we are making a switch to SemVer in order to make it easier for the community to understand when breaking API and data format changes are made.
I agree the README is out of date. It will have to be cleaned up. In the meantime refer to the changelog and release notes for information about v4 and future releases.