Status of the project

[astrojuanlu]

Hi everyone, some months ago I asked about the status of the project:

today I was casually glancing at mkdocs/mkdocs and saw no commit activity since May (couple of months ago). wondering if the project is already considered "feature complete" (and most of the work is happening in mkdocstrings/mkdocstrings plus mkdocs-material) or if the development halted because of something else

to which @oprypin replied

it is indeed feature -complete and there was kind of a vision to reject feature requests that could instead be plugins. buut yea there's no new vision other than that so it's kind of stalled. some stuff is still happening, but slowly, because i don't have much motivation.

Now we're evaluating Sphinx alternatives for Kedro, and naturally MkDocs is the one that gets mentioned the most. Looking at the most recent PR the CI looks mostly healthy, which is impressive given how fast these things rot (apart from a small problem reported recently). However, I am somewhat concerned about the status of the project:

• There have been zero pull requests merged since November 7 (last one). Even though one could say that MkDocs is feature complete, at least there could be some acknowledgement of these contributions, or automatic reply, or triaging, or "thank you" of any sort, but it's not happening, even for low-hanging fruit like this.
• There is a number of unaddressed issues, in the recent past, and it's not clear whether they are feature requests, support questions, or actual bugs, because there is no triaging going on.
• There was some necroposting in this old discussion recently, and I don't think the new issues were followed-up on, namely the fragmentation of the mkdocs plugin community.
• Although some of the MkDocs extensions seem to be healthier than the core project itself (mkdocstrings, Material for MkDocs), by looking at the theme wiki it's not clear to me whether there are other themes being maintained (all of them were last touched in 2020 or earlier, except Material and Windmill and a small Japanese theme).

The main thing that would reassure me about the future of the project would be some systematic (not a one-off effort) triaging of issues and pull requests. If MkDocs is feature complete, so be it - but that would need to be clearly stated in the documentation, the contributing guides, and the pull request tempaltes. And if folks keep opening issues, it would be good to at least try to reproduce them or label them accordingly.

Thanks everybody for your time, looking forward to hearing your thoughts.

[astrojuanlu]

Hi @Andre601, thanks for sharing your thoughts. Would you point to what, in your opinion, signals that the project is still alive? Gitter/Matrix discussions, plugin activity, forks, something else? Any qualitative or quantitative indicator I can look at?

[squidfunk]

Maintainer of Material for MkDocs here. Given that I have been developing Material for MkDocs for the last 7 years, extending MkDocs capabilities with 10 plugins (and counting), I'd consider MkDocs stable, mature and rather feature-complete. Nonetheless, IMHO, this project definitely needs active maintainership to review PRs and triage existing issues.

My time to work on Open Source is entirely consumed by Material for MkDocs and this likely won't change in the coming years, given how much stuff there's still to do, so I personally can't step up as a maintainer of MkDocs itself. However, I'm happy to send some of the funding that Material for MkDocs receives upstream if somebody wants to step up and commit to maintaining MkDocs. I'm already funding developers maintaining MkDocs plugins that are integrated with Material for MkDocs, as well as @facelessuser for maintaining the awesome and essential Pymdown Extensions package.

[ultrabug]

Maintainer of MkDocs here. There are many aspects to take into account when trying to judge a project's liveliness which indeed vary from an individual to another.

IMHO what makes an OSS project alive is its community first. Do you feel that MkDocs core is actively slowing down its community and ecosystem? If I read Martin's and Andre's comments, I don't feel like it.

@oprypin and I tried to setup Gitter/Matrix but the traction is not great. I must admit for my part as well that I fail at keeping up with yet another communication tool for a single OSS project. So I wouldn't be judging the project on instant communication tools either.

Could we do better in triage/PR answering? Sure. I for one don't feel good about it, doing my best and actually replied to a few of them last week... Merging PRs is another story where I also feel I could do better but I stick to what we agreed a while ago with @oprypin that he's merging them since he's planning the releases. Maybe I could step up better there.

I'd like to say that anyone could help with triage without being maintainer of the project by simply answering and giving their opinion. That's what an active community is for, not only maintainers, no matter how many of us get appointed.

Since you asked for quantitative indicators, let's look at the project's activity since its creation:

As you can see, the project has actually seen worse periods of low activity and yet, we're still alive and kicking! 😀
I hope you feel that way too for this great project and for the amazing work and creativity of its community ❤️

Kindly

[pawamoy]

To keep the same style as the others: mkdocstrings maintainer here 🤣

My personal feeling is that the MkDocs ecosystem and community is thriving. I even think it woke up the Sphinx ecosystem and community when they saw how popular MkDocs-and-friends got 🙂

I sometimes answer issues here (easy ones). I don't have much more time to give to MkDocs, but I'd be happy to get a bit more privileges to at least close issues or move them to discussions when needed.

[ssbarnea]

IMHO, I think that mkdocs ecosystem is awesome but mkdocs itself might need some time/love/stewardship. It does much better than Sphinx but we it could also do much better.

We really need a group of cores on mkdocs that can help with maintenance, even if they might not have the time to implement or fix bugs themselves, only to unblock stuff, perform CI/CD maintenance and ensure that the project is moving forward.

I also think that the best people to be part of this group are the creators and maintainers of the most popular extensions, as they have a strong interest in keeping mkdocs alive long term, @squidfunk @oprypin and @pawamoy are few names that come into my mind.

I could allocate few hours per week to help the project if needed as I want it to really thrive, not only surprive. I would even go so far to promote the use of mkdocs organization as an umbrella for hosting extensions created by others, the same way we have with @tox-dev @PyCQA @sphinx-contrib or @jazzband - This being a key factor in bringing folks together, like using the same matrix chat channel, github discussions, being able to step-up and help one extension if its current maintainer is unreachable.

I do know that sometimes people might have disagreements but if we all agree that mkdocs future is the number one priority, I hope that we can join the efforts to and move forward. What do you think?

[squidfunk]

I think it's essential that we move forward.

As in the past, I'm happy to comment on mentions and give input, especially from the perspective of a theme dev, but unfortunately, I'm not able to implement something beyond rather uninvolved PRs. I think most would agree that my time is best invested into Material for MkDocs, one of the most popular themes of MkDocs, pushing stuff forward on the frontend end.

[ssbarnea]

My assumption that all of us will sooner or later stop maintaining/nurturing our projects and for this reason I plan from start to make the transition to the next maintainer as easy as possible, minimizing the impact on users. That is why I avoid maintaining projects under personal github account and ensure that the github organization has at least 2 admins (preferably 3). In fact I even have a "successor" configured on https://github.com/settings/admin

Nobody is obliged to do anything, I only mentioned people that I expected to have an interest. A project can be helped even without doing active coding work, sometimes even just engaging on discussions like this could be seen more than enough.

[trel]

Just a vote from the quiet end of the table...

The current project, maintenance, response times, and feature set seem perfectly great. This project does not appear to demand a real-time support apparatus. Async discussions and issues tracked at GitHub feel like the correct balance already.

And of course, interested parties can always move the open code forward for their own purposes. Bonus points for taking the time and effort to get that work merged back into the main repo.