How stable is the partial hierarchy for overriding purposes?
mhelvens opened this issue · comments
I've been making thankful use of the ability to override partials. I override partials that are included by others, and I override partials that include others.
By explicitly allowing this, you have essentially made the entire partial hierarchy part of the public API of dmd. I'd just like to make sure: can I be confident that my overrides will continue to function when I update dmd?
It must be tempting for you to refactor this stuff now and then. But strictly speaking, whenever you do this, it is a breaking change and according to semantic versioning you'd need to increment the major version number.
What is your policy w.r.t. this issue? Thanks!
you’re absolutely right, the dmd partial hierarchy is part of the public API so yes, major versions will be updated on breaking change.. and yes, a massive refactor of the partials is imminent as it’s just too complex for a regular user to quickly find which partial needs editing.. Also, the plugin-creation workflow is currently too complex/slow.
i have a half-finished dmd “playground” which will make understanding and overriding dmd easier, but it’s probably a month or two away..
so don’t worry, i’m aware and will be careful.. if any future release does break anything, please let me know asap..
Thanks! Very clear.
you're welcome.. one other thing - if your overrides improve the look/feel of the generated docs let's bundle them up as a plugin, for others to enjoy.. or pull them in the to main project! Either way, we can credit you on the main readmes.. cheers :)
I'm currently still playing around with them, but there are indeed some features that would be nice in the main project. For example, I'm currently working on a way to skip the full body of inherited properties, and to instead provide a list of hyperlinks to the originals.
I'd be happy to contribute. But if you're planning a major refactoring, I guess I'd better wait until after.
I'm currently still playing around with them, but there are indeed some features that would be nice in the main project. For example, I'm currently working on a way to skip the full body of inherited properties, and to instead provide a list of hyperlinks to the originals.
this is the intended default behaviour - something is amiss here.. i will take a closer look at your project / jsdoc-documentation later.. although, that might be hard as i left my laptop on the tube a couple of days ago! still pissed about that.. but i will look asap.
I'd be happy to contribute. But if you're planning a major refactoring, I guess I'd better wait until after.
no need to wait - your contributions will be invaluable at any point.. any contribution received against master will still be factored into development branches, if they exist..
this is the intended default behaviour - something is amiss here.. i will take a closer look at your project / jsdoc-documentation later
Ah, this doesn't manifest in the link I gave you. You can look at the last revision of delta.js instead. For example, the DeltaJs#Delta#applicationCondition property is inherited by a whole bunch of Delta subclasses, and seems to be fully repeated each time.
no need to wait
OK. I'll see what I can do. Would you prefer contributions in the form of a plugin, or a pull request to the main repo?
Ah, this doesn't manifest in the link I gave you. You can look at the last revision of delta.js instead. For example, the DeltaJs#Delta#applicationCondition property is inherited by a whole bunch of Delta subclasses, and is fully repeated each time.
ok, thanks.. will take a deeper look asap..
OK. I'll see what I can do. Would you prefer contributions in the form of a plugin, or a pull request to the main repo?
we’ll see.. if we think the updates are something all users would prefer, then let’s pull it in.. otherwise, it’s probably safer to start with an optional plugin.. if use of the plugin becomes “defacto” then yes, it will definitely get pulled in..