search

rust-lang / mdBook

Create book from markdown files. Like Gitbook but implemented in Rust
https://rust-lang.github.io/mdBook/
Mozilla Public License 2.0
18.13k stars 1.63k forks source link

Are we looking for more maintainers? #1589

Closed msathis closed 3 years ago

msathis commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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:

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 commented 3 years ago

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

ISSOtm commented 3 years ago

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 commented 3 years ago

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

sanmai-NL commented 3 years ago

Still looking for maintainers, or can this be closed?

ehuss commented 3 years ago

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 commented 2 years ago

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 commented 2 years ago

@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 commented 2 years ago

Alright. Do you want any means of private contact?

Dylan-DPC commented 2 years ago

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 commented 2 years ago

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

Dylan-DPC commented 2 years ago

i'm @DPC on zulip

KFearsoff commented 12 months ago

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 :stuck_out_tongue:

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

You can check my contributions to https://github.com/NixOS/nixpkgs and my inputs in https://github.com/NixOS/rfcs/pull/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 commented 11 months ago

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 commented 11 months ago

@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 https://github.com/rust-lang/mdBook/issues/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. https://github.com/rust-lang/mdBook/pull/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:

Let me know if you have any questions.

KFearsoff commented 11 months ago

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 commented 11 months ago

Another task that could be helpful is creating releases. I try to do that at least once a month, but sometimes I get behind. https://github.com/rust-lang/mdBook/pull/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 commented 11 months ago 
* 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.