Community contributed features and Insiders?

[polarathene]

Just curious how feature contributions from community are released. Are they also put behind the Insiders exclusivity window?:

New features first land in Insiders, which means that sponsors will have access immediately. Every feature is tied to a funding goal in monthly subscriptions.

There is no dates associated to the achieved funding goals, I don't know what rate these are going to be reached at, so $4k (related to the back-to-top button feature) isn't helpful without monitoring the current funding value displayed there over time. All I know is it will increment monthly based on some amount, which is again unclear what that roughly is.

If a feature like those on the insiders roadmap was contributed, would it be available to all users or will it always go through the Insiders process which a contributor might not be a member of? Or does that depend based on your involvement in the PR? Or is the general stance that additional features shouldn't be contributed to this project but maintained as separate theme extensions / plugins by community?

Eg for the mermaid.js feature at the $5k goal, I don't know how long it took to reach the current $1.5k in funding. If I maintain my own variant (as I assume even if you did welcome feature contributions to the project that weren't restricted to insiders, that existing Insiders features would be rejected), is there a reliable way to detect when an alternative implementation is going to conflict once an insiders features is released to the community edition?

I'm guessing this isn't a concern for you so it's a non-issue on your end. Despite advocating users implement solutions themselves externally (which is understandable sometimes) that you may reject/delay but later tackle for mkdocs-material.

EDIT: I did see an issue for Prairie Fire at the $1k mark reached on Dec 22. I'm not sure how often the current funding is updated, but that's been at least 2 months, so an average of around $250+ per month? (I don't have anything against this sponsorware model btw, I think it's pretty cool)

[squidfunk]

That's a great discussion, thanks for opening it.

Just curious how feature contributions from community are released. Are they also put behind the Insiders exclusivity window?:

No. Everything that happens in the public repository, stays in the public repository.

Maybe a bit of background before answering your other questions: I did a survey on the user demographics and target audience last year and released the results on Twitter (if you're interested). In fact, only a very small percentage (< 10%) of the users of this project actually would consider themselves frontend engineers. Also, knowledge of CSS/JS is rather limited. This is an HTML (+CSS/JS) template, so for most things I'd call a feature (rather than an enhancement or bugfix) you'll need experience in 2 out of 3 languages. In the last 5 years (we actually missed the birthday, as v0 was released on Februrary 9, 2016 😅) there were very few pull requests that added functionality that would fall in this category. I guess this would be totally different on a JS-based static site generator like Docusaurus or VuePress, because frontend developers seem to prefer JavaScript-based SSGs.

This means that the one pushing this project forward in the end is me, which is also why I've started the sponsoring model last year because after 4 years it felt kind of odd when you invest a significant fraction of your time, answering issues and implementing feature requests for other users, and then companies like Netflix and Amazon start using your software but you? Well, you get nothing, buddy, because you did all the work for free. Insiders is an attempt to be compensated for my time I put into this project.

Now, your questions:

If a feature like those on the insiders roadmap was contributed, would it be available to all users or will it always go through the Insiders process which a contributor might not be a member of? Or does that depend based on your involvement in the PR? Or is the general stance that additional features shouldn't be contributed to this project but maintained as separate theme extensions / plugins by community?

This is a tough question, because most features interfere with the internals of this project, and every feature needs to be compatible with all other features (or should be). The main point being: instant loading. Getting this right can be tricky at times. So, a back-to-top button sounds trivial, sure, but integrating it with the rest of what's already there is not. All solutions I've seen posted in comments were incomplete. But, if a user issues a pull request for a feature, has tested it with instant loading, made sure it works with all other feature flags, documented it and it fits into the general feel of the theme (smooth animations, good UX, fits the design), then I'm happy to merge it and kick if off the Insiders list, thus make it available to everyone. However, I don't have the time to guide you through the process of achieving that level of completeness, as in that time I'd just implement it myself. I hope you agree.

It's also perfectly fine to advertise solutions in discussions (as has been done a few times) or advertise a plugin you've made. Discussions are a perfect place to share these kinds of solutions and I'm happy when this is done. I've currently pinned one of the discussions regarding multi-language search because I was blown away by the level of detail that was put into it, and think it's a great guide for other users trying to achieve the same thing.

Eg for the mermaid.js feature at the $5k goal, I don't know how long it took to reach the current $1.5k in funding. If I maintain my own variant (as I assume even if you did welcome feature contributions to the project that weren't restricted to insiders, that existing Insiders features would be rejected), is there a reliable way to detect when an alternative implementation is going to conflict once an insiders features is released to the community edition?

I wouldn't merge PRs for features that are already in Insiders, that's correct. That wouldn't make any sense, because the configuration and implementation will very likely be different, and when the Insiders version gets merged it would mean a new major release and breaking changes (likely) every time. One of the cool things about Insiders is that it is completely compatible with the non-Insiders version. Yes, things are rendered differently (or not at all, for Mermaid diagrams, which will just remain code blocks), but there are not incompatibilities.

I try to be as open as possible about how much funding I get and when goals are reached, but I haven't managed to set up a dashboard. The graph currently looks like this:

So yes, your guess is right, it's currently at around $ 250 a month with solid growth, so by the projections Mermaid should be released at a later time at this year. However, that's not a guarantee, as I can't anticipate if some users will cancel their subscriptions when certain funding goals are reached.

I hope I could shed some light on the reasoning behind Insiders and how it's currently going. Note that the data in the Insiders documentation is always fresh (sometimes +15m), so you can check back from time to time to extrapolate when goals are reached.

[polarathene]

I guess this would be totally different on a JS-based static site generator like Docusaurus or VuePress, because frontend developers seem to prefer JavaScript-based SSGs.

I was actually going to push for Docusaurus for the project I'm contributing to. However as the maintainers aren't web devs themselves (like myself), and mkdocs-material has much better typography and features out of the box - I felt it was a better choice for them.

I did mention the perks of an Insiders subscription but didn't get any bites 😛

Insiders is an attempt to be compensated for my time I put into this project.

I absolutely support that and think it's a terrific idea, you deserve it 👍

Getting this right can be tricky at times. So, a back-to-top button sounds trivial, sure, but integrating it with the rest of what's already there is not.

Yes, I understand that. It gets more complicated as the feature set grows with time too.

This is generally why I preferred Docusaurus, as dealing with React for SSG is far much nicer in that respect, especially when maintaining third-party workarounds if required.

I've contributed to projects in the past, and I'm well aware how what seems simple to tackle initially can drag on into a lengthy PR to get right and suitable for the broader community and project maintenance.

Whereas these features would be far easier to implement in a shorter time as specific workarounds, not ideal but much lower initial effort vs upstreaming.

However, I don't have the time to guide you through the process of achieving that level of completeness, as in that time I'd just implement it myself. I hope you agree.

I do agree 👍

One of the cool things about Insiders is that it is completely compatible with the non-Insiders version. Yes, things are rendered differently (or not at all, for Mermaid diagrams, which will just remain code blocks), but there are not incompatibilities.

That's good, especially with the insider features arriving to the community edition via major version updates. That way no major surprises should happen with third-party modifications when updating unless it's a major version. I'm happy with that.

My main concern was regarding that scenario where if it takes 1 year or so for the mermaid support, and I choose to implement myself for a project that needs it (from a quick evaluation the plugin wasn't quite reliable, and the superfences authors approach is nice but has some drawbacks I'd rather avoid given the demographic I'm producing the docs site for); that when that feature lands, it's going to conflict with my approach which may be perfectly adequate.

As such any third-party modifications do impose risk of breakage, even if the features aren't at parity or even related. I know I've already had a few discussions with yourself where you've been pretty fast to reject accepting features into mkdocs-material, no matter how much I may try to justify it. That's understandable, you've got a popular project here, you can't say yes to everything and your time is valuable.

I try to be as open as possible about how much funding I get and when goals are reached, but I haven't managed to set up a dashboard. The graph currently looks like this

That's awesome, thanks for sharing.

You've been a very responsive and friendly maintainer to interact with which is fantastic 😁

[squidfunk]

My main concern was regarding that scenario where if it takes 1 year or so for the mermaid support, and I choose to implement myself for a project that needs it (from a quick evaluation the plugin wasn't quite reliable, and the superfences authors approach is nice but has some drawbacks I'd rather avoid given the demographic I'm producing the docs site for); that when that feature lands, it's going to conflict with my approach which may be perfectly adequate.

You should be able remove your custom JS/CSS, as you can see from the documentation that the configuration for the native Mermaid integration is trivial (only SuperFences) and it integrates with instant loading and dark mode out of the box. Other than that, $ 10 for handing the maintenance for that over to me (and get all other benefits) should basically be a no-brainer, but I can see that paying money for Open Source still may feel weird.

As such any third-party modifications do impose risk of breakage, even if the features aren't at parity or even related. I know I've already had a few discussions with yourself where you've been pretty fast to reject accepting features into mkdocs-material, no matter how much I may try to justify it. That's understandable, you've got a popular project here, you can't say yes to everything and your time is valuable.

The problem is that you really need to be careful what you integrate for the reasons stated in my first comment. It may look trivial from outside, but certain things sometimes just don't fit into the overall architecture and concept. See my comments on those separate issues.

You've been a very responsive and friendly maintainer to interact with which is fantastic 😁

Thanks. If I reject proposals or enhancement fast sometimes, it means I'm caring a lot about this project and don't want the issue backlog to grow to a degree where it's out of control. That can happen extremely quickly. I try always to answer in a way that makes my decision clear and comprehendable. If in question, don't hesitate to ask for further clarification.

[polarathene]

You should be able remove your custom JS/CSS, as you can see from the documentation that the configuration for the native Mermaid integration is trivial (only SuperFences) and it integrates with instant loading and dark mode out of the box.

I've already evaluated the existing open-source alternatives. As stated the plugin wasn't adequate, it had certain issues and I don't have time to contribute to another project at this point.

The superfences author's implementation is more invasive but works much better, however it relies on snippets to conditionally load and a few other concerns I had that I can address better. I don't mind DIYing an improvement on that solution. I realize your project has experimental status alternative that's much better integrated, but as that's not available under the current circumstances and is likely to take a year to reach at the current rate, I might as well be open to my DIY approach.

---

Other than that, $ 10 for handing the maintenance for that over to me (and get all other benefits) should basically be a no-brainer, but I can see that paying money for Open Source still may feel weird.

I don't have an issue with paying when it's for my own deployment. I'm contributing docs for an open-source project that I contribute features to but Github Wiki was not satisfactory for that project anymore. We evaluated our options and mkdocs-material was voted as the most desirable choice to go forward with.

I'm not a member of that organization personally, and I'm not going to pay $10/month for every open-source community I decide to assist with for docs. They can enjoy the docs and setup I assist with for free out of my own time, and if they want to enjoy the benefits of Insiders that's up to them to support you directly. I have mentioned the benefits multiple times.

---

The problem is that you really need to be careful what you integrate for the reasons stated in my first comment.

I don't have much options when upstream dismisses my suggestions / requests to the point that not even a contribution is welcome for it or may face considerable friction.

I've contributed features before that took over a month, had maintainers be supportive/encouraging towards doing so, only to later reject my work in favor of their own that implemented solutions from my PRs without attribution... not that you seem to be the type but it has made me reluctant towards lengthy contributions.

It may look trivial from outside, but certain things sometimes just don't fit into the overall architecture and concept. See my comments on those separate issues.

I'm aware.

Sometimes it's also just a difference in dev experience however (as in accumulated knowledge/experiences). Often I've solved problems from insights elsewhere or another dev makes me aware of something I didn't know that makes a solution easier (or as you point out, discovering what we don't know and getting the opposite outcome).

it means I'm caring a lot about this project and don't want the issue backlog to grow to a degree where it's out of control.

All good, as you should.

If more users chime in on those features being desired, especially your Insiders users, I imagine you'd reconsider them. I stretch myself out a bit too much with my volunteer work, prioritizing your time and knowing when to say no is important for open-source 😅