Open adam-p opened 11 years ago
I'm upgrading the priority of this issue. There was recently a bug (#70) that was fixed by a change to the CSS. Users won't get this fix if their CSS doesn't get updated.
So, I started working on this (in the css-update
branch). I wrote up a plan and after a few days it's nearing completion.
Then last night I thought to myself, I really should have posted the plan/design/workflow I came up with to the Github issue before I started it, in case anyone had any alterations/corrections/revelations. (This is a pretty obvious thing, that a developer should always do when working on a team, but it still usually feels like I'm working on this in a vacuum. Will anyone even see this?)
And then I started wondering, what sorts of feedback might I get? Maybe small changes? Maybe entirely different approaches? ...And then I realized that I've implemented the whole default/custom options thing wrong from the very start, a year ago.
But first, here's the plan I came up with:
(The merge stuff is implemented. The checksum-checking stuff is started.)
Okay, so: How CSS customization should have been done from the beginning...
First, how it's done now: The default CSS gets dumped into a text box, saved in the user's options, and the user can edit it.
What would have been better: The default CSS lurks behind the scenes, and the user gets an empty-ish text box where they can add their own CSS rules, which override the defaults. That way we can change the default without worrying about the user's custom mods.
It's so obvious. I had trouble sleeping last night after realizing it, and I'm still displeased. (I mean, I can see why I implemented it the way I did at first -- fastest path to something that worked, I was just making it for myself, blah blah blah. But it wouldn't have been a ton more effort to do it right. Lack of foresight.)
What now?
I haven't decided yet. But my thinking is...
Anyone have any thoughts, suggestions, feedback, jibes, revelations?
I have created a new issue for the redesign: #78
feels like I'm working on this in a vacuum. Will anyone even see this?
I'd always suggest posting it anyway, even if you get no feedback, to serve as documentation for yourself and others in future, and as a timeline of MDH's development.
For a project with 1.2k+ stars and almost 100 forks, I'm surprised it's so quiet around here.
I'd always suggest posting it anyway, even if you get no feedback, to serve as documentation for yourself and others in future, and as a timeline of MDH's development.
I totally agree, and I plan on following your advice. Even thinking about writing out the CSS issue helped me to rubber-duck it. And all coders should hone their written communication ability. And, yeah, what you said.
For a project with 1.2k+ stars and almost 100 forks, I'm surprised it's so quiet around here.
Also @hupili:
I just find that adam-p is the only code contributor in this project... Amazing. One person solely drives a 1K+ star project so far~
To be fair, @bordaigorl contributed a diff (in #26) 7 months ago, which added math support. But... that's still just one contribution, so your point is still valid.
My paranoid concern is that there aren't any pull requests because my code in impenetrable. I've been thinking about writing a code tour/development guide to help anyone who feels like digging in.
It's also certainly true (IMHO) that developing MDH is much more... dirty than, say, a standalone library. MDH is a) an end-user tool that b) has to operate in a large number of environments and c) on a large number of sites. When I do a full test, I use Chrome, Chromium, Firefox, Thunderbird, Postbox, and Safari (and soon Opera), and send and receive email with Gmail, Hotmail, Yahoo, Thunderbird, and Postbox. (And never mind Ice Dove, Pale Moon, and the outstanding Chrome extension feedback I have that portable Chrome doesn't work.) Oh, and, of course, changes in the client apps and webmail pages mess MDH stuff up every few months. And each release gets pushed out immediately to all ~10000 users, so if it's broken... bad news.
So it's not just a matter of running some auto-tests and benchmarks and knowing that it works. (Although... I could be doing a much better job of creating auto-tests. I need to look into Selenium or something to do some browser-driving. The few "engine" auto-tests I have so far have been invaluable.)
I have also added some "features" to MDH that make it even dirtier and special-case-y than it already would have been. For example, there are deviations from the Markdown spec to make it easier for users to, say, paste a pre-formatted link into an email. (Plus the TeX math support is a deviation.) That creates a bunch of unintended bugs (some still outstanding!) and means that when, say, @anstosa graciously suggests that he might do a HTML-to-MD reverter (#33) I have to give him a laundry list of caveats and exceptions that are clearly off-putting.
Well, that turned into a whiny rant. Sorry about that.
To end on a more positive note: I enjoy working on Markdown Here, and I'm thrilled that other people use it. If I never get a pull request, that's okay. I do my best to make sure people can contact me every which way, so they can contribute/participate with words/ideas/bugs. I do most of the MDH work in the open, and I'll make sure I do that even more. Also, I have ideas for better modularity and plug-in-ness (e.g., there are lots of requests input other than MD, and output other than rendered HTML). If I can create some better, more testable boundaries between pieces, it will be easier and cleaner for people to help out.
@adam-p , thanks for the pointer. I just cloned the project and did a git log
. Amazingly, there is only one name... I think the idea of MDH is very good and many people should be willing to improve it. Problem is that the project is already big enough for me to catch up in a short period of time.
I scanned the notes, issues, and wikis. I never see any project owners make notes around in such details and in this particular careful manner. I had similar experience, sometimes a bit frustrated. I was always hoping more people will appreciate my ideas and come to work together. I'm constantly trying to refactor code, making it easier. I write more demos, and blog about it. I improve the doc. Things had not paid off so far, but I expect it become better.
I think the open source world is composed of a bunch of busy people. Unless there is something quick to do, few people will spend the effort. The diff contribution you pointed is one example. In my project, someone also demo-ed good improvement points. I appreciated it very much. However, going from an idea to thorough engineering is still a long way, especially when you want to perform a complete testing with other components of the project. The demo contributor just stopped at that point, without PR. Then I did the rest engineering works and also put him in the contributor list. I don't think there is a problem of such behaviour. I appreciate diff contributors and demo contributors very much. It would be much better to have (more) PR contributors.
That's the landscape here and we can not change it easily. The reason why it looks like a vacuum is that the messages here are not pushed to other people. If not for this @
-sign of me, next time I come here might be several weeks later... Or when I encounter problems. Although I come here now, I have not read this issue (or other pointers in it) thoroughly... I only read relevant part to me and scanned it to get a general idea of the discussions. There are other people watching here, but they are busier than me who even doesn't have time to leave a word. I suggest to go for an email list first, e.g. Google Group. At least, we can have more casual discussions and more immediate response. I think those people who open issues or leave comments in the repo will be glad to join. When you have milestones or important ideas, you can announce there. Then I don't have to wander around every several weeks and trying to dig up important information. By important information, I mean that is relevant and suitable for me. For example, a very small and quick fix may be important to me. I'm seriously looking for that. I think it applies to many other people.
@hupili: Thanks for your thoughtful comments. I agree entirely.
If the default "Primary Styling CSS" or the user's currently selected "Syntax Highlighting CSS" changes in a release, and the user hasn't modified the previous default, then the user's styles should update to the new default.
Alternatively, the user could be prompted. Perhaps they prefer the previous default -- even though the new one should be better (by some measure) or it wouldn't have been changed.
I guess the ideal would be to save the previously set CSS as an easily selectable value, in case the user wants to revert, and set the new default as the current. (An even-more-fanciful ideal might be to diff/merge the new and the user's current, and only replace those rules that haven't been modified. That's getting pretty tricky/dangerous, though.)
For new users, this could be mitigated by not immediately writing the default as the user's setting. Then it would only get set if they modified it.
This problem is especially heinous right now because a default CSS change in 2.7.0 was needed for the new Markdown table column alignment to work. But users have to manually reset their CSS or else it appears broken. For example: https://github.com/adam-p/markdown-here/issues/47