Are we looking for more maintainers?

[msathis]

I understand that maintainers have a lot to focus on, from daily life to work to open source. But at the same time, i feel this project has the potential to be the modern, performant alternative to mkDocs.

I can see a lot of PRs waiting for review, issues waiting for replies. Can we add additional maintainers to ease the burden of current maintainers?

Hope no one gets offended by this as it's not my intention. Thanks for the amazing project! ❤️.

[joshrotenberg]

I have bandwidth for, at the very least, helping out with issue triage and labelling, in addition to fixing bugs as they come in. Would love to offer more help.

[ehuss]

Of course more maintainers would be nice. Anyone is welcome to respond to issues or provide reviews for PRs or help with testing. I'll also update the contributing guide with a little more information.

If someone wants to look at some issues, here are some that are top of my mind:

• Rust edition 2021 support #1593 — Needs to be implemented soon.
• header.hbs renders above the top of the HTML document, out of view #1331 — Needs a web expert.
• Preprocessor output files are deleted when hbs renderer is called (from mdBook > 0.3.1) #1087 — There are some PRs for this, but it is a big design issue that will take some careful consideration.
• Buttons still overlap code #1322 — There have been several PRs for this, but all of them have had issues.
• Warn on unknown configuration settings #1595
• A surprising number of PRs and issues come in regarding setting up CI. There are about a hundred ways to set up CI, with different providers, different approaches, different deployment scenarios, different needs, etc. I'm not sure what to do here, since making the CI docs a hundred pages long probably wouldn't help, and trying to explain how to use the ins-and-outs of every provider is also out of scope. I'm uncertain why people are having such difficulties.
• Consider the design for extending the default theme in general. Several PRs roll in wanting to add this or that specific thing, but I'm wondering if there are better ways to add extension points. Some examples: Add a logo to the navigation bar of the HTML rendered book #1584, Add before_body_end handlebars partial #1531, support google analytics 4 property #1481, theme: Update google analytics #1290 (I would like to remove the analytics option, and just make it possible to embed javascript in the page), Include template #1271. There are also some regarding the menu bar I can't find right now (like adding additional icons to the top). I don't want to add too many extension points, since they can make it more difficult to change things later (like the {{> header}} issue linked above). However, adding dozens of little "add this little icon here" is also probably not a good approach. I'm unsure of what approach to take.

There's lots more, and I'm sure each individual has their own things they would like to see, which makes it difficult to prioritize and manage. Also, a lot of PRs are "drive-by" in nature, where someone drops a change they want, and then when it is merged, they don't come back to help when the PR results in issues. This makes maintenance even harder because it puts the burden of supporting more new things on me.

Let me know if you have any questions, or specific things you want to help with.

[djcarpe]

Pick @joshrotenberg, he won’t shut up about Rust and MDBook. Skilled and passionate. The two ingredients for real magic.

[ISSOtm]

Hi, I'm just a random user! :) But I'm still volunteering ^^

I actively use mdBook (two-fold), so I'd love to see it evolve and thrive. I'm already somewhat busy with other projects, so I could "only" help with issue triage & PR review, and likely not tackle the bug reports myself.

I believe that this would still be useful, as a significant PR backlog may be deterring to contributors (if only because of merge conflicts). My own PRs have not received any feedback, and my downstream projects would benefit from the changes; so while I understand the lack of maintainer time, it still feels discouraging.

I have previous maintainership experience on gbdev/rgbds and more of that org's projects, including an active technical documentation using mdBook.

Is there a channel (Zulip or anything) where one can discuss with maintainers? This would be useful to e.g. keep the above "important issues" list updated, receive some feedback more quickly, etc.

[simonmichael]

+1 for a mdbook chat room, even if it must be non-matrix.

[sanmai-NL]

Still looking for maintainers, or can this be closed?

[ehuss]

Yea, I think almost every rust-lang project is open to more maintainers. Anyone that wants to help with reviews or responding to issues would be very appreciated!

[ISSOtm]

I have been crawling through the bug tracker for a while, and I'm noticing that quite a few actually have mergeable PRs that have been sitting for a while. Are more maintainers needed? (I can volunteer.)

[Dylan-DPC]

@ISSOtm yeh both of us are currently more focussed with rust-lang/rust and other repos so I guess wouldn't mind having more people on the team. Given that this is a rust-lang repo, it's a bit more complicated in terms of ownership, so we'll have to discuss and see how that goes

[ISSOtm]

Alright. Do you want any means of private contact?

[Dylan-DPC]

We don't have a place to communicate at the moment so you can contact either me or ehuss on zulip. I'm available on discord servers as well

[ISSOtm]

Done so, though I don't know what your username on Zulip is.

[Dylan-DPC]

i'm @DPC on zulip

[KFearsoff]

Hi, I'm very interested in becoming affiliated with the project. I've used it in a few private and proprietary projects and have been blown away by how amazing it feels to interface with!

It looks like the project has been led by some really skilled people! But skilled people are busy, and I feel like me being less technically proficient is actually a benefit here 😛

I feel like my contribution will be largely organizational rather than technical. I'd like to:

• Go over open PRs; link related issues, if they are not linked already
• Merge ready, easy PRs: simple fixes, trivial features, already implemented in code and reviewed; close outdated PRs (I've seen a few that have actually been resolved without being closed)
• Go over open issues: close outdated ones and implemented ones, improve visibility for those that are still relevant. Unfortunately, a lot of the feature requests will probably have to be postponed while I'm going over issues, but I'll try not to overlook any PRs
• This should hopefully make it clear how the next few minor releases would look like

You can check my contributions to https://github.com/NixOS/nixpkgs and my inputs in NixOS/rfcs#109 to see if I make a good candidate communication- and management-wise. I'm a little hesitant to start contributing to mdBook because I fear my contributions will take even more of the little bandwidth the team already has.

You can contact me in this issue directly, or in Matrix at @kfears:matrix.org. I'm not in Zulip but I'm open to try it.

[ehuss]

Hi @KFearsoff ! Thanks for offering to help, it is very much appreciated! I'll try to get back to you soon with some answers to your questions. Those all sound like helpful things. Labeling and responding to issues is also helpful. I'll also try to go through a few PRs soon, too. I'm also a little bit behind on making a new release.

[ehuss]

@KFearsoff Sorry for the slow response.

Also, who should I ask to get a better on understanding of who the main stakeholders and consumers of mdbook are/which features they are waiting for/etc.?

In terms of maintenance, the primary consumers that I am concerned with are those in the rust-lang org, which is used for our documentation and various team projects and websites. I'm not aware of anyone waiting for any major features. If I have time and interest, I'll try to review changes that aren't directly related to that, but it tends to be a much lower priority.

I posted in #1655 a bit about maintainership and reviewing PRs and the kinds of things that would be helpful. If you follow this repo, you can see some of the kinds of reviews that I do, and responding to issues. It would be a big help if others helped respond to questions in issues, check if bug reports have sufficient reproductions, check for duplicates, add labels (particularly the A-* labels), etc.

Reviewing HTML/CSS/Javascript changes tend to be some of the most difficult, since I have not done web development for decades, and a lot of that can be very delicate, and troublesome dealing with lots of different browsers and platforms.

Another task that could be helpful is creating releases. I try to do that at least once a month, but sometimes I get behind. #2253 is an example of what that looks like (documented here).

AFAIK, there aren't any pressing issues. There are changes that could improve mdbook overall, but I don't have a real set of priorities. Some that I can think of off the top of my head are:

• Start work on the 0.5 release. I want to split off the preprocessor/renderer code into a separate crate to significantly reduce the overhead for writing preprocessors. However, I need to do research to see which APIs preprocessors and renderers need. I also want to start trimming the public API, since there is way too much exposed right now.
  • I've also been contemplating a new preprocessor protocol for the new release, but I'm not sure if aiming for that would delay the release too much.
• MathJax support could use some love. There are a few PRs open to improve things, and there is a bunch of interest on the pulldown-cmark side of things of taking a different approach (see Math spec pulldown-cmark/pulldown-cmark#733). But it isn't clear to me the best way to package mathjax and support newer versions and deal with various build-time options. Or maybe the best answer is to recommend to users to use mdbook-katex instead?
• It would be really good to get a new highlighting engine. We are stuck on an old version of highlight.js which is just going to get worse over time. As a band-aid, if someone could figure out how to migrate to the new version, that would be helpful. Or, if someone could put some effort into moving Using syntect as a higlighting backend rather than highlight.js #1652 forward, that would be nice. I like the idea of doing build-time highlighting, but was a little concerned about the performance hit. I don't remember what the state of that PR is, but I would love to see that improved.
• Improving the testsuite. Right now, the coverage isn't particularly great (particularly for the CLI commands). I would also like to make it easier to define test books, so we don't have to keep extending the dummy_book for each test. I have made a few false starts on that, but haven't really made much progress.

Let me know if you have any questions.

[KFearsoff]

Thanks for the detailed response!

In terms of maintenance, the primary consumers that I am concerned with are those in the rust-lang org, which is used for our documentation and various team projects and websites. I'm not aware of anyone waiting for any major features.

Understood.

If you follow this repo, you can see some of the kinds of reviews that I do, and responding to issues.

I'm trying to do my best at that, but I guess I'm not enough of a Rustacean, because my bar for "LGTM" appears to be much lower, haha.

It would be a big help if others helped respond to questions in issues, check if bug reports have sufficient reproductions, check for duplicates, add labels (particularly the A-* labels), etc.

From looking over the issues we have open, I found that a lot of them are actually quite reproducible. It's honestly incredible how there are pretty much no heisenbugs.

Also, this is probably not a discussion for Github issues, but I find that the current tagging system employed is not particularly useful for actually reducing the amount of open issues. I'm a huge fan of user pain system, because it's very easy to understand, provides an extremely clear prioritization model, and gives you valuable metrics to track. This goes especially well with sane Agile.

Of course, you'd have to adapt those systems according to the project's needs (from what I understand, stability and robustness is number 1 priority by far), working on open source (which means you don't really have customers who'll want a refund, which actually makes things harder to track), and so on. But I think the foundation is very solid. And using Github Milestones for user stories is also quite helpful to keep track of things. A lot of stuff that I did (PR reviews, issue answers, my PR) have to do with Docker support: it would be cool if we had a Docker milestone that links to all of that!

Reviewing HTML/CSS/Javascript changes tend to be some of the most difficult, since I have not done web development for decades, and a lot of that can be very delicate, and troublesome dealing with lots of different browsers and platforms.

I feel you. The frontend stuff is painful.

I feel like that is also the most brittle part that we currently have. The Rust side is extremely solid, but on frontend there are a lot of things that can be done, and making any change whatsoever is really scary.

I'm trying to turn mdbook into a personal blog website on my free time, so I'm extra invested in that part. I'm really not much of a web dev, but HTMX and Hyperscript help me get some work done: I also think it will lead to some great extensibility and ease-of-use, since it's all HTML. I'll submit a PoC with a patchset when I'm confident that this approach scales.

Another task that could be helpful is creating releases. I try to do that at least once a month, but sometimes I get behind. #2253 is an example of what that looks like (documented here).

This is a little hard for me to get the grasp on without user stories or advanced bug triaging, I'm sorry.

* It would be really good to get a new highlighting engine. We are stuck on an old version of highlight.js which is just going to get worse over time. As a band-aid, if someone could figure out how to migrate to the new version, that would be helpful. Or, if someone could put some effort into moving [Using syntect as a higlighting backend rather than highlight.js #1652](https://github.com/rust-lang/mdBook/pull/1652) forward, that would be nice. I like the idea of doing build-time highlighting, but was a little concerned about the performance hit. I don't remember what the state of that PR is, but I would love to see that improved.

I think I'll look into it and provide some feedback in relevant PRs/issues.

* Improving the testsuite. Right now, the coverage isn't particularly great (particularly for the CLI commands). I would also like to make it easier to define test books, so we don't have to keep extending the `dummy_book` for each test. I have made a few false starts on that, but haven't really made much progress.

I'm not sure how that's even going to work. I'm not sure if I can be of much help here, but can you explain what you have in mind on how to define/generate test books?

[Dylan-DPC]

Another task that could be helpful is creating releases. I try to do that at least once a month, but sometimes I get behind. #2253 is an example of what that looks like (documented here).

I guess i could help doing some of the releases when you can't, need to check if I have the necessary permissions

[KFearsoff]

* Start work on the 0.5 release. I want to split off the preprocessor/renderer code into a separate crate to significantly reduce the overhead for writing preprocessors. However, I need to do research to see which APIs preprocessors and renderers need. I also want to start trimming the public API, since there is way too much exposed right now.

Could we consider doing a 0.5 release earlier? The milestone we currently have is pretty modest, aside from #1330. And #1330 is pretty huge, so it would be great to get it up-to-date and merge it sooner rather than later, because it already bitrotted a bit, and it won't get any better if we continue holding off doing it. I guess including #2049 too would make some sense too.

* It would be really good to get a new highlighting engine. We are stuck on an old version of highlight.js which is just going to get worse over time. As a band-aid, if someone could figure out how to migrate to the new version, that would be helpful. Or, if someone could put some effort into moving [Using syntect as a higlighting backend rather than highlight.js #1652](https://github.com/rust-lang/mdBook/pull/1652) forward, that would be nice. I like the idea of doing build-time highlighting, but was a little concerned about the performance hit. I don't remember what the state of that PR is, but I would love to see that improved.

Working on it!

Given the amount of changes the PR makes, I'd also like to see it merged sooner rather than later because solving all of the merge conflicts is a pain. It could be before 0.5 or after, but I'd like to avoid trying to get it in 0.5.

@KFearsoff Sorry for the slow response.

No worries. I checked your maintenance load (issues and PRs) and... wow that's a lot. I assumed it to be the case, but... wow.

This is kinda why I started by talking about commit rights and stuff. I feel like I definitely have more throughput than you, and well, I don't want your inbox to become more noisy by spamming "merge this" on PRs that don't have much inherent complexity. Nor do I want to ping you with "close this" on issues that have bitrotted away/are duplicates/are basically WONTFIX/etc.

Alternatively, we could consider a different system of assigning priority to issues and PRs. I linked to the "user pain" above - maybe we could use something like that so that it's easy for you to know which things are worth looking at.