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.
-
|
Hey @d0ugal, long time no talk 👋 I hope you're well! No worries! This is why we're going to revisit those, in order to sharpen the focus of the project and put maintenance onto more shoulders |
Beta Was this translation helpful? Give feedback.
-
|
I suspect that most issues which were tagged with "needs design decision" before we added support for third-part themes and/or plugins can be closed. I know that I have closed many of them in the past, but I never took the time to go through them all. When there was no way for third parties to add their own functionality, it made sense to punt the decision down the road. But now, the best approach is to suggest a third-party theme or template be used to implement the requested feature and then be open to make adjustments to the various APIs to allow the feature to be implemented. I suspect a response which states as much could be used to close many of these old feature requests. |
Beta Was this translation helpful? Give feedback.
-
|
Again, fully agree. I've written a theme and many plugins for MkDocs, and my experience is: MkDocs' main USP is its awesome extension capabilities. IMHO, improving them and keeping them sharp should be our focus, but that's only my view. If we can agree on this, we can close many issues an modernize the project to be ready for what's to come. If not, we will also find a way forward. IMHO, for each issue, we should check if there's a plugin that supports this (or can be implemented), if there's a customization that can be employed, or if it's just out of scope. Grooming the backlog could be a great basis for deciding on the vision. |
Beta Was this translation helpful? Give feedback.
-
|
@squidfunk Fully agree. Extensibility is the key to success IMHO. What I would want to do specifically for any issue we identify as being appropriate to be solved via a plugin, is to ask ourselves - what changes could we make to the plugin framework to make implementing this "easy." We should then set to work on expanding the framework, and then to ship a small plugin (if it is not too much work) that solves to original request. I could see us falling into two working teams:
A model like this would create a new feedback loop internally, and ultimately lead to a (smaller?) more extensible core, along with a robust library of extensions that people can begin using. This also gives more ways for people to contribute to the project - as people can contribute to extensions much more easily than they can to the core - which requires much deeper knowledge of the project. You know? |
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.
-
|
This space's purpose is exactly for us to find out and define that!
Couldn't agree more. In my opinion, making MkDocs make do as few things as possible, while allowing to implement as much as possible via hooks, plugins and other extension mechanisms should be the way forward, since this would allow to basically implement almost anything on top of a solid foundation. Keeping MkDocs as unopinionated and general as possible would allow for maximum flexibility. I've written 12 plugins and am missing almost nothing. However, I'm not the only plugin author, which is why we need to get a detailed top-level view on what is necessary to decide. Also, we might isolate some commonalities among different plugins which we could centralize in a utilities library, making writing plugins even simper. IMHO, grooming the backlog is the best way to start, as we can re-evaluate all prior feature requests in that light. Disclaimer: this is only my personal opinion from my very own experience, and others may have different views. However, if somebody has a different vision, she or he should be committed to actually achieve that vision. |
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.
-
|
@tomchristie thanks! Everyone: if you disagree with an issue being closed, this discussion is the perfect place to ask for it to be re-opened and discussed more. As a side note, obviously out-of-scope issues can be closed with a short message stating so, and for more complex ones I'd appreciate if we could give some reasoning why we closed, and if possible provide escape hatches (example: #3623 (comment)). |
Beta Was this translation helpful? Give feedback.
-
|
@tomchristie you've closed some issues without providing a why. Could you maybe please write a short comment when closing issues why you reached the decision to close them? Also, I thought we wanted to do a consolidated effort on backlog grooming, because since you've been away from the project for quite some time, you could be lacking context in some aspects. Some issues you closed without an explanation:
Don't get me wrong – it is your project, so feel free to close anything you want, but IMHO, closing things without a proper explanation or with only throwing a "won't happen" at the user is not what I would want as somebody going through the troubles of writing up an issue or feature request. |
Beta Was this translation helpful? Give feedback.
-
|
Sure thing yep, I've added some context on each of those. |
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.
-
|
Thanks @squidfunk, I gave my available slots on the Doodle 👍 Let see if others want to join, otherwise I suggest we use either the first one on Saturday, or the first one on Monday depending on your preference 🙂 (or both!) |
Beta Was this translation helpful? Give feedback.
-
|
Great, so it looks like we're going to talk on Sunday, April 14, 10:00 AM (UTC+2). We can use this Google Meet: |
Beta Was this translation helpful? Give feedback.
-
|
I feel my American education has failed me. I am pretty sure this is 9 hours ahead of me in California (it took me forever to figure that out). That is 1am my time, so I am afraid I won’t be able to make it. |
Beta Was this translation helpful? Give feedback.
-
|
I'm sure we're going to need a second call, that we can schedule more in favor of your time. I'm going to be in UTC+1 from the beginning of May again, but I also don't need to be on every call. |
Beta Was this translation helpful? Give feedback.
-
|
@byrnereese If it helps, Doodle seem to use your configured local time (or is it based on IP address?) when showing hours of the day. |
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.
-
|
(playful nudge: hey there's others of us here as well ya know) |
Beta Was this translation helpful? Give feedback.
-
|
@tomchristie You're right! |
Beta Was this translation helpful? Give feedback.
-
|
IMHO, this should be a team effort, which is why I've suggested multiple times to do this on a joint video call, which we're scheduled for Sunday. Additionally, those issues already have existing labels – what happens with them? |
Beta Was this translation helpful? Give feedback.
-
|
@tomchristie erm, do you still want to do the call on Sunday? 😅 You've actively closed so many issues on the issue tracker, I'm wondering if you still want our input or can decide on the scope of MkDocs by yourself. Both is fine for me. |
Beta Was this translation helpful? Give feedback.
-
|
(Just figured I'd make a start where I can.)
Yep, was assuming we're still on. |
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.
-
|
Update @pawamoy and I did three more calls and have invested a total of 4-5 hours. We're almost done with our first pass. We still need to comment and close some issues, and will do one more call next week. @tomchristie are you okay with how we did so far? We always tried to offer alternative solutions if things could be solved with plugins or some customizations, but we've also considered some things out of scope. We hope that this aligns with your vision of the project. If not, please reopen and let's discuss! |
Beta Was this translation helpful? Give feedback.
-
|
50 issues 😛 |
Beta Was this translation helpful? Give feedback.
-
|
You're killing it! |
Beta Was this translation helpful? Give feedback.
-
|
No you 👉 👈 |
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-deploybut don't push #3047mkdocsandreadthedocsthemes into installable third-party-packages. #3190Issues that are or can (and maybe should) be implemented as plugins:
rel=externalon 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