Dan, I like the idea of moving documentation to eST and Sphynx or .md files, at least for beanquery. If we make documentation to be a part of the original source code and make a policy that documentation shall always be updated when a new feature is added (e.g. via PR), then this shall hopefully make sure documentation stays up to date.
I saw a lot of very nice features implemented in beanquery (thank you very much for managing it), but documentation was never updated, which is really pity. I hope this can still be recovered, because one thing is to formally describe new feature, explain the thinking behind it and how author intended to use it. Since beanquery by its nature is very flexible and very versatile, having a good documentation is also very essential there. Also, I think beanquery is one of the things, what makes beancount very distinct from hledger and ledger, so having a good documentation shall help to attract new people to the community. Regarding speed improvement in v3: my *.beancount file is 7.8 MB, contains transactions from the last 20 years in 130k lines and speed was never a problem to me, I personally can wait till Martin's retirement when he plans to move it to Rust (of whatever new language he will want to play with by that moment). On Monday, June 10, 2024 at 11:04:16 AM UTC+2 [email protected] wrote: > On 10/06/24 09:27, Stefano Zacchiroli wrote: > > On Sun, Jun 09, 2024 at 07:45:22PM -0400, Martin Blais wrote: > >> I'm hoping to restart v3 in Rust at some point and to maybe write a > >> proto generator for a Rust-native data structure at that time. Well, > >> you know, probably in retirement if I'm realistic, unless someone else > >> does it. > > > > The current v2/v3 split is very bad for the Beancount community right > > now. If there is an existential risk for this (amazing!) community, it > > lies there. I can elaborate on why I think that's the case, but I'd > > rather focus on positive/actionable stuff. It's great that you > > acknowledge publicly you won't have the time to do it yourself in the > > near future. But I don't feel anyone feels empowered right now to > > proceed with the Rust re-implementation of v3 you suggest. I think it > > needs to be advertised clearly that there is a need to do so and you, as > > Beancount leader, approve of that plan. Maybe a ROADMAP document > > somewhere, or a pinned issue on GitHub clearly saying so. It won't take > > a lot of time, but would be really beneficial for the community. > > I also think that the v2/v3 situation is unfortunate and I have been > thinking for a while about redefining the plans for a 3.0.0 release. > > v3 is intended to be the C++ core rewrite, but it seems that this will > not happen any time soon, or ever. The reason for the C++ rewrite is > mostly performance. The rewrite was seen as the occasion to clean up > some long-standing issues that require important changes to the core. I > think a more evolutionary approach could better match the available > resources. > > I would be very happy if beancount 3.0.0 would simply become the release > in which the "leaf" tools (beangulp, beanquery, beanprice, etc) are > split into separate projects. The git master could be released more or > less in the current status as beancount 3.0.0. > > There are a few things needed for this to happen: > > - Make sure that all bugs fixed in the v2 branch are also fixed in the > master branch. This just requires going through the git log for the two > branches. There should not be much in the v2 branch. > > - Release at least beangulp, beanquery, and benaprice on PyPI. I > released beangulp recently. I'm planning to clean up some loose ends in > beanquery and release a 0.1.0 version soon. beanprice probably needs > some cleanups too. I can take care of that too, if there are no other > volunteers. Is there any other component moved to other repositories > that people use? > > - Update the documentation to reflect the current state. It is a bit of > a longer term plan, but for beangulp and beanquery, my plan is to move > the documentation to reST and Sphynx. I think it would make sense to > have the beancount documentation in the same format. Using Google Docs > as the master for the documentation was thought to enable easier > contributions to the documentation. However, I don't see many of these. > I think Sphynx is a much nicer way to produce the documentation and it > would allow for easier inter-project references. > > - Do some cleanup in the project. Moving the C++ code to a dedicated > branch, alongside the Bazel build definition is high on my list, simply > because it is a source of confusion, and because it make the source > distribution much larger. > > On the top of my head, there are two pull request against the master > branch that would make sense to merge for a v3 release: replacing the > current parser with the parser based on Re/Flex and the improved grammar > from the C++ rewrite, and the re-implementation the 'import' directive > to be a literal import rather than the more complex and much less > intuitive thing it is now. > > The latter is a compatibility break (unless we introduce the new > 'import' semantic under a new name, but that would not allow to get rid > of the code implementing the current semantic, which would hold back > some important simplification) thus it would be nice to have it for the > 3.0.0 release. IIRC, the parser improvements make the handling of > indentation stricter, thus are also a compatibility break. However less > sever and it could be part of a 3.1.0 release. > > Cheers, > Dan > > -- You received this message because you are subscribed to the Google Groups "Beancount" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/beancount/3ac4293f-66c0-4176-b91b-d4bed6d059dfn%40googlegroups.com.
