x4 docs in a subdirectory named x3 - why?

[daixtrose]

The documentation is in doc/x3, but I expect the docs to be in x4. What hinders you from running a git mv on that directory?

[saki7]

doc/x3 directory is currently unmodified and copied as-is from the old boostorg/spirit repository.

The transition process from X3 to X4 is still in progress, and it requires decent amount of work; see #1. We're currently focusing on improving the core functionalities, and planning to update the documentation later.

A simple modification, such as git mv or s/x3/x4/g would not work, as the API of X3 and X4 are not fully compatible. The documentation needs entire overhaul.

At the least, we already have built a consensus on migrating QuickBook to AsciiDoc (Antora).

[saki7]

To clarify: the initial development of X4 is not as simple as renaming "X3" to "X4". Since the creation of X4 is a result of the breaking changes being unaccepted in X3, I decided to incorporate all sorts of breaking changes and API overhaul in the initial release of X4. The summary is #1, and we're still in progress. Therefore, the documentation also needs overhaul.

[daixtrose]

Please do not read the following as criticism. Feel free to proceed as planned, since I appreciate someone taking the initiative to bring Boost.Spirit to the latest C++ standard.

Your completely acceptable and surely successful approach leaves out the opportunity for constructive feedback from others about the user interface design.

If you could start by writing a comprehensive document outlining what you are trying to achieve and including it in a merge request, then potential library users could review it and provide comments on what they think should be different from a user's perspective.

Given that some interface decisions will be taken while evaluating different techniques, I do not expect a 100% finalized document. Yet, such a documentation could help describe the roadmap you already have in mind.

[saki7]

Your completely acceptable and surely successful approach leaves out the opportunity for constructive feedback from others about the user interface design.

I think this is indeed a valid concern, but I'm afraid that it boils down to human resource issue. While it is possible to open a pull request and wait for some people to get involved, the question is: who is going to assure the validity of the new design, and how much time should we wait for?

If Spirit.X3 was a library with a decent amount of active contributors, it's relatively easy, and pretty much common to follow such procedure. However, from my recent maintenance experience, we rarely see outside collaborators commenting on PRs (see: https://github.com/boostorg/spirit/pulls?q=is%3Apr+is%3Aclosed).

Of course, I'm always open for technical discussions; in fact I occasionally request a mini-review from outside collaborator, e.g. #53 (comment).

As a usual procedure, I'm definitely going to file a pull request for the new documentation. I'm thinking that I should keep the PR open for some decent amount of time, to get feedback from people who have some technical insights. That said, the documentation overhaul is going to be a huge PR that includes the whole content describing the entirety of our library.

Generally speaking, I don't think it's realistic, for any open source project, to wait for some outside collaborators to review such massive PR voluntarily. So there's nothing that prevents anyone from posting technical comments, but there's going to be a deadline for realistic reasons.

At least, such reviewer should take a look on majority of the pull requests I submitted to X4 (which are summarized in #1), because most of the technical decisions for the API-incompatible changes are actually described in the pull request body.

[saki7]

If you have a very specific concern about some specific feature, you may preliminarily request me to @mention your username.

For example, if you have some concerns like below, please feel free to comment:

• I want to be @mentioned when there's API changes in error handlers
• I want to take part in refining the design of the semantic actions
• I want to write some chapters of the new documentation

[daixtrose]

• I am happy to write some chapters of the new documentation.
• I would like to ask to be @mentioned when there's a significant change in the user interface.

[saki7]

I am happy to write some chapters of the new documentation.

I'm glad to hear that. I'm going to submit the initial version of the documentation anyway, because we need a starting point that explains the status quo of the library. I'm imagining a minimal "Quick Reference" shall be provided by the core maintainer (me) in the first place. Further discussions can then take place as a follow-up PR that fills the lacking content of the documentation.

I would like to ask to be @mentioned when there's a significant change in the user interface.

Sure, I can cooperate, but you should be more specific. Which component of the X4 are you interested in?