What I meant was if external contributions won’t be ignored and will be considered 
What I meant was if external contributions won’t be ignored and will be considered
Understood.
I’m game for helping land doc. changes.
M
As promised, here is the doc on FDB feature status: FDB Feature Status · apple/foundationdb Wiki · GitHub . We’ll probably update the page regularly going forward.
4 Likes
This looks good! I assume several entries like Tenants and Changefeed are maintained by Snowflake team. (and would need their confirmation)
Maybe someone from Snowflake can comment.
Cool, perhaps you should also update or remove this page: Experimental-Features — FoundationDB ON documentation to point users to the GitHub wiki? Is it the long term plan to go with the wiki and drop those docs too?
Also is it possible to update FoundationDB Release 7.0 Planning · apple/foundationdb Wiki · GitHub to point out what actually made it in 7.0?
I also would like to say that it may be best that many documents on the GitHub Wiki is moved to a dedicated folder lke the design directory.
This way people can PR changes, compared to wikis which can only be managed by collaborators.
Ideally:
- The “design” directory contains documentation about internals, and project management
- The “documentation” directory contains API documentation, high-level overviews, and operation guides
From what I know:
- Scaling: ???
- Redwood: released
- TLog Backups: in progress
- Storage cache: replaced by
rangeconfig - Fast restore: seems to be cancelled, replaced by new TLog backups + partitioned backups
- gRPC: in progress
- Keyspace copying improvements: Seems to be mostly work on range-locks (does not work with changefeed) and Changefeeds
- Read/write aware data distribution: released
- New memory storage engine: released(?)
- Report conflicting keys: released
- Changefeeds: seem to be in progress work by Snowflake, primarily for “blob granules”
When testing them I encountered a bug that slows down data distribution significantly when a changefeed accumulates changes + a shard split is triggered.
1 Like
I’d really hoping the team would respond to the question (I can certainly read the wiki) since even just regarding gRPC, the wiki states:
Adding gRPC endpoints for certain client/server communications, e.g., some fdbcli usage, file transfer to and from fdbserver processes.
While the original planning doc states:
Stable wire protocol - (AJ) - Re-implement our bindings to use a gRPC protocol for handling client requests. This will eliminate the need for the multi-version client, so upgrades will become much easier. It will also remove our use of JNI, making the Java bindings much more efficient.
The later of course is very desirable (to remove JNI) but I am not sure if that’s still the plan now. Again, docs need to have an expiration date on them or just tag as obsolete so folks aren’t going to read them thinking that by using FDB 7.0 they should see these features. If the feature matrix is canonical, then we need to tag everything else as obsolete, otherwise, we just made the problem worse, not better…
It may be the x86 builds that are signed.
Just catching up here. I think the issue Clement raises here is absolutely essential to answer to guide the future of FoundationDB. The sad truth is that huge swaths of the docs and getting started guides published online are literally unchanged from 10+ years ago when I wrote them. Limitations that existed back then are still documented but long since transcended in the code. Guidance that made sense for version 2 makes little sense for version 7.
The fundamental problem is that the large companies that improve and maintain FDB have no immediate need for these docs to be updated, especially ones related to getting started, or to small/medium scale operational best practices.
There are two paths I see: 1) These companies decide to prioritize DX for FDB as an investment in FDBs ubiquity and future, spurring the creation of layers, increasing developer engagement, usage, etc. that will ultimately benefit them. 2) FDB remains a powerful tool, but it drifts further away from the “average” developer’s toolkit and the ecosystem withers.
I hope for the sake of the project that an initiative could be organized, perhaps shared between a few of the big contributors like Snowflake and Apple, to build a modern docs website, and updated information about FDB features, capabilities, and best practices.
7 Likes
I like the idea that “an initiative could be organized, perhaps shared between a few of the big contributors like Snowflake and Apple, to build a modern docs website, and updated information about FDB features, capabilities, and best practices.”
Just throw some thoughts here.
Reality: FDB has been used in production in quite a number of companies, range from large scale deployment to small ones. However, there is no commercial company behind it to provide support. The current development is mainly driven by a small team in Apple, and the community contributed quite a few bug fixes and improvement. The core team in Apple is often smaller than teams in other companies that use FDB (we have more features that we want to work on than the people we have).
Specific confusions about features: There are various reasons for a large number of experimental features: 1) some features naturally need quite a long time to become mature for production use, e.g., about four years for RocksDB storage engine; 2) some features were de-prioritized or superseded by others, e.g., dynamic knobs and storage cache; 3) some features have scope changes, e.g., gRPC; 4) some features need new owners, e.g., Redwood, meta-cluster, tenant.
The path forward: My proposal is that core developers continue to improve the product. At the same time, the community can step up in two ways: 1) help each other in onboard documentation, best practices, finding and potentially fixing bugs (which the core team is happy to do for reproducible issues); 2) contribute back in layers, core features, bug fixes, or documentation changes. For documentation, my proposal is to improve https://apple.github.io/foundationdb/ for general use of FDB, and https://github.com/apple/foundationdb/tree/main/design for FDB internals.
I use FoundationDB in production but at a smaller scale.
It has been by far the most reliable database I have used and I have not had any incident relating to FoundationDB, compared to other components.
While I would like to be able to contribute to FoundationDB in some manner, it feels like there is too much knowledge and information about the codebase locked up inside Apple/Snowflake. I most likely can’t contribute at a large scale but it would be great if there were more efforts to help onboard contributors and answer codebase questions, small or large.
I believe that this is beneficial to FoundationDB. A support-only model would result in attempts to commercialize core features for being too “enterprise-y” and would give the support company more of an incentive to make the codebase impossible to touch for external companies.
This of course has drawbacks as contributions only come from companies for the sole purpose of improving their use cases, which would be fine and cover almost everyone at a large scale, but due to the perceived complexity and history of how FoundationDB came to be compared to other databases means it is not enough.
Another unrelated thing: it is surprising that Redwood has currently no owner, it has performed extremely well for me, and compared to RocksDB it would perform significantly better at range-reads which are common for medium-sized blobs in my use case (32KB-1MB) and high amounts of index lookups due to it being a B-tree-like design.
(also, RocksDB does not inspire confidence for me considering it is built on LevelDB, it’s not the same thing anymore but still…)
Some thoughts:
- Wondering out loud if the ecosystem would indeed benefit better if there is a commerical company behind it for support. If there’s enough interest, I am sure we can find money to fund people to “deal” with the stuff that a vibrant community would need but the core team at Apple could not be reasonably expected to provide. It’s either a volunteering effort (it could be ran like the CNCF to improve involvement from various “larger” teams) or folks figure out some kind of paid consulting/support service (to help teams deal with things like upgrade, scaling, figuring out errors — stuff that might make a good lifestyle gig for some).
- Layers are great but people need to maintain them (a lot of them are experimental-hey-I-built-kafka repos which probably is inspiration for folks but not truly a supported layer that people should rely on). Record Layer is the exception here (it’s great!).
- I do think there’s good argument to-be-had to just use GH wikis instead of sphinx as the later is probably a bit more modern in 2025… The search/navigation experience on the sphinx page isn’t that great.
- If we stick with sphinx, I suppose we need someone (is it @saintstack?) to help land the changes. We should still probably agree on what the ideal DX would look like. We also would need to figure out what the wiki pages on GH are for as well. Again, ideally you want one place for users to focus on for using FDB.
- I am pretty sure an agentic coding assistant can ingest all the docs/wikis/forums and write a new doc site in an afternoon but we need to (again) decide on whether that’s what we want or do we want just to fine-tune the pages today.
I think we should consider another documentation generator. GH wikis do not have good access control and can’t benefit from the PR process at all.
Those should all be moved to either design/ or docs/.,
I think much of the clean up involves removing duplicates, irrelevant pages and consolidation. Not sure if letting an LLM do it is a good idea
My proposal is that core developers continue to improve the product. At the same time, the community can step up in two ways: 1) help each other in onboard documentation, best practices…
I think this is quite unrealistic. “The community” has no idea about the details of how FoundationDB has evolved from version to version. Asking the community to look at the release notes between 2015 (when the docs are from) and now and update the docs is quite silly. I think @panghy’s idea of getting an AI to build a modern starting point by distilling everything that exists publicly is a great idea, but it still probably only really works if a team them takes that result, does an editing pass, then continues to update it to stay in sync with the changes in new versions. I can hardly force Apple to prioritize updating the docs, but I think we are talking about a <0.1% incremental effort (compared to the XXX person-years of work that has gone into the codebase) to build a modern set of docs.
…finding and potentially fixing bugs (which the core team is happy to do for reproducible issues); 2) contribute back in layers, core features, bug fixes, or documentation changes.
You know damn well no one finds bugs . But seriously, the community can absolutely build and maintain layers, monitoring tools, code samples, etc. But I stand by there being no realistic way for anyone outside the dev team to address the core docs.
As a concrete suggestion, it would be great just to build a small starter set of modern docs pages. By keeping it small, you also minimize the work to update them. You can provide a link in the new docs to the old FoundationDB 7.4.3 — FoundationDB ON documentation , but mark everything there as deprecated. These new docs pages don’t need to be exhaustive, they “just” need to explain the current state of the product, the main features (and what’s experimental!), how to get started, and basic operational best practices. I don’t know if the API references are up to date at all (they still include warnings about version 2!) but if they are you could pull them in too.
I co-founded this project so I have a vested interested, but come on, you (Apple, Snowflake) guys are stewards of one of the most amazing open source technologies on the planet. I’m not asking for ad campaigns, just enough up-to-date information about the system so that others can dig in, get started, benefit, and contribute a bit more easily.
3 Likes
I would like to start some basic work on documentation, and would like to know the community’s opinion on using MkDocs as a documentation generator:
- Yes, use MkDocs
- No, stay with Sphinx
- No, use another documentation generator (please reply!)
0
voters
My idea is that we could develop the documentation on a fork repository with all interested contributors added while it is still WIP, and when we have most of the basics down, merge it into main with a PR.
I am game to help review, merge, and post doc. patches. I don’t think an alternate doc engine is the answer to our dissipated, stale doc problem so would vote no on #1 and #3 above.
S
The idea is we switch in addition to writing new docs. I am currently working on some basic FDB operating pages.
I admire the enthusiasm but I don’t think we are at the stage where we should we writing stuff just yet @semisol, I do think @daverosenthal point on who’s going to maintain them going forward and whether we will take the (painful) step of deprecating all existing docs (keep them around for posterity of course) is important before we go and build more docs (I believe I made that point in an earlier reply as well).
Once we have all party’s buy-in:
- Core Developers (from Apple) could agree to the smaller starter set of modern docs and change their current workflow to them (doesn’t affect design docs) which means freezing the sphinx docs
- Snowflake Developers will also have to agree to helping document at least the things they have contributed. If they have forked FDB at this point and is unwilling to do so, we should seriously consider the long-term maintainability and public guidance of those features
- A group of volunteers would have to decide on the audience, structure, objective of the first pass of documentation with some idea of who should do what and what’s the point when we would merge to main (i.e. who’s signing off the whole thing or is this a “good enough, merge as we go thing” – I don’t think for a seriously complicated project like FoundationDB we can to do that honestly)
Only then can the community rally together and have an intelligent effort going forward.