Backlog cleanup #3675
Replies: 0 comments 31 replies
-
Thanks a lot for taking the time to go through the list of issues @squidfunk 🙂 |
Beta Was this translation helpful? Give feedback.
-
Hey, it’s nice to see these being looked at. I think I created and started using “needs design decision” to put off decisions where I wasn’t sure what to do! in hindsight it was a bit of an anti pattern Sorry for leaving you with my indecision and procrastination 😀 |
Beta Was this translation helpful? Give feedback.
-
Is there some consensus about what's in scope for the MkDocs project vs. what's the purview of plugins? For example, the cache-busting issue could be handled by a plugin, though if MkDocs was more opinionated, it could inject some cache-control meta tags during build time. I'm happy to take a stab at some of these things, though I do believe that MkDocs, being a lightweight, extensible core, is its primary strength. |
Beta Was this translation helpful? Give feedback.
-
Seems like @tomchristie did a first pass of the backlog today and closed almost 20 issues ✌️ |
Beta Was this translation helpful? Give feedback.
-
Quick question: do we want to use the "close" feature of (public) discussions? It might make sense for very big repositories, or for teams with different ways of managing discussions, but maybe not for us? I don't have a strong opinion on this, anything is fine as long as we're consistent. |
Beta Was this translation helpful? Give feedback.
-
I've created a Doodle with 10 time slots that would work for me. I'm currently in UTC+7, so I tried to schedule them so that it works at least for all of you that live in Europe. I've also added Saturday and Sunday, because I understand that many people will not be able to make it during the week. I hope we can find a slot until the end of the week, so we can start grooming the backlog. I've scheduled 2 hours, but I think we will need more to go through 100 issues. I'm open to extending the call if we realize that we need more time, or schedule a follow up call. Looking forward to working with all of you! |
Beta Was this translation helpful? Give feedback.
-
The inner workings of MkDocs are not my forte, but may I suggest an action that I learnt from experience with issue lists (and other items like database tables, which tend to grow like trees): tagging. It has to do with qualification and classification of items, and cutting a big and confused problem into smaller, manageable chunks. But it should be driven first and foremost by practicality. Taking @squidfunk's cue :
Following Wikipatterns (themselves an expansion of version control philosophy), we might agree on the principle of it's better to ask for forgiveness than permission? (Since it's easy to revert to an earlier state). Meaning @squidfunk could boldly tag those issues he has already surveyed the way he deems best? Then, if somebody disagreed, they could just express their view. But at least we would have a starting point? |
Beta Was this translation helpful? Give feedback.
-
First call done! Thanks @squidfunk and @tomchristie for your time! Everyone: all three had a chance to talk about a bit more than backlog grooming, and in the end didn't have a lot of time to groom, so we only closed a few issues. Feel free to comment on them further, either here or in each issue. @squidfunk and I can dedicate time so we try to move forward, but every decision can be reversed if you feel like it should. Additionally, we started using the "Project" feature of GitHub, see https://github.com/orgs/mkdocs/projects/1/views/1. IIUC @squidfunk is successfully using it for Material for MkDocs, and I myself use it occasionally on other projects. Happy to get feedback on that part too 🙂 To summarize: we'd like to move the ReadTheDocs theme out of core, as well as the |
Beta Was this translation helpful? Give feedback.
-
Dear valued maintainers and contributors,
MkDocs has a significant backlog of over 120 open issues. Many of these issues are outdated, stale, or tagged with "needs design decision", and may no longer align with the project's scope and vision. To ensure that MkDocs evolves effectively, it's essential to invest time in grooming this backlog. IMHO, here are some examples:
Issues that could be considered out of scope:
gh-deploy
but don't push #3047mkdocs
andreadthedocs
themes into installable third-party-packages. #3190Issues that are or can (and maybe should) be implemented as plugins:
rel=external
on external links #1639 (likely not generalizable)Issues related to themes, that we might consider moving out of core:
Miscellaneous things:
I firmly believe that collectively addressing these issues will enable us to clarify our vision for MkDocs and streamline its development process. Therefore, I propose organizing a collaborative effort to review and decide the fate of these issues. Please note that the above selection is just a first skim I did that I'd love to discuss.
In the coming days, I will share specific dates for a series of Google Meet calls dedicated to this grooming process. These sessions will provide a platform for all members of our community to contribute their insights and perspectives. Together, we can determine which issues to close, which to retain, and how best to prioritize our efforts moving forward.
Your participation in this endeavor is invaluable, and I encourage everyone to join these discussions and share their thoughts. By working together, we can ensure that MkDocs continues to meet the evolving needs of its users and maintain its position as a leading documentation platform.
Let us know what you think.
Beta Was this translation helpful? Give feedback.
All reactions