search

picocms / Pico

Pico is a stupidly simple, blazing fast, flat file CMS.
http://picocms.org/
MIT License
3.81k stars 615 forks source link

Pico 3.0 #535

Open PhrozenByte opened 4 years ago

PhrozenByte commented 4 years ago

Since the issues with our old dependencies kinda got out of hand lately (see #528, #534 and 8a44584291685e5e163765ed6578c184c991794e), it's time to kick-start development of Pico 3.0 :tada:

Major changes are going to be updated dependencies (Twig 3.0+ and Symfony YAML 5.0+) and lifting the requirements to PHP 7.2.5+. We definitely won't implement all of #317, but rather focus on lazy page discovery and loading. We definitely won't overhaul Pico's event system now, neither will we implement caching or i18n support with Pico 3.0 (maybe with Pico 3.1? :thinking:).

We'll also think about changing Pico's Markdown parser. Unfortunately Parsedown's development process got very unreliable lately. However, there's a lot to consider - not just BC, but also performance-wise (Parsedown is by far the most performant Markdown parser I know). Thus there's no decision made yet. Other opinions are very welcome on this topic! Also see e.g. #576

Pico 3.0 is a major release, thus it will break BC. As always, Pico's official PicoDeprecated plugin (Pull Request) will do its best to maintain BC. However, be warned, we'll explicitly drop all pre-v1.0 and v1.0 behaviour that affects performance.

As always, feedback is highly appreciated! :heart:

Ideas

Release of Pico v3.0.0-alpha.1

Since the mentioned issues are affecting live installations already, I decided to release a intermediate Pico v3.0.0-alpha.1. This release upgrades Pico's dependencies to Twig 2.12, Symfony YAML 3.4, Parsedown 1.7.4 and Parsedown Extra 0.8.1 for now (requiring PHP 7.0.8+). Both are still officially supported and are basically drop-in replacements, since they maintain BC on a best-effort basis ("best-effort" means "should work for most users", there can still be issues for some users). Pico v3.0.0-alpha.1 is meant as a fast solution for all people experiencing the issues mentioned above.

Feedback about Pico v3.0.0-alpha.1 is highly appreciated, especially regarding issues! :+1:

Related links

Major changes

Resolves #528, Resolves #534 Fixes #602, Fixes #603, Fixes #608, Fixes #623

dajare commented 4 years ago

If you are considering alternatives to Parsedown (and its Extra), you could have a look at Markdown-it, although I don't know how well its technologies integrate with Pico's environment. I've become familiar with it on the TopAnswers.xyz platform, where it seems to be performing well.

mayamcdougall commented 2 years ago

@PhrozenByte, I wasn't trying to "light a fire under you" on getting this done. 🔥😓

I just wanted to offer to take some of the burden off you if you needed me to...

(And also pacify some of the ongoing questions people keep been asking.)

Just let me know if I've overstepped. 😔

PhrozenByte commented 2 years ago

Nah, no worries, it's fine. This needs to be done and a little kick in the ass helps :sweat_smile: :see_no_evil: :wink:

As far as I remember anything should be done now code-wise. Pico is working locally again. This will be Pico 3.0 even though the only "real" change are the updated dependencies (most other changes are code cleanups and syntax updates), because it still breaks backwards compatibility (and in a "hard" way, i.e. PicoDeprecated can't help here).

Since Travis CI is dead we must move our CI pipeline to GitHub Actions. I hope I'll find some time in the next couple of days (again... :unamused:) and that it doesn't take too much time. And, of course, Pico 3.0 needs testing...

If you wanna help you can draft the upgrade news (like https://picocms.org/in-depth/upgrade-pico-21/), primarily targeting the changes in our dependencies:

None of the changes should be a big issue, but nevertheless, we should document them... Naturally we also need the common stuff like how to upgrade, but I guess you could simply copy this. Thanks :+1:

mayamcdougall commented 2 years ago

Nah, no worries, it's fine. This needs to be done and a little kick in the ass helps 😅 🙈

Alright, lol. And ditto, it usually helps me too. 😉

(But I also know you're usually busy.)

If I can help it, I don't like to leave questions on the Issue tracker unanswered... even if I don't actually have an answer. Sometimes you answer comments right away... and sometimes it takes you a week, lol, and I don't like leaving people in limbo in the meantime.

I've been meaning to add that PHP 8 warning to the readme for awhile, but I've been lazy about it too. 😂

Since Travis CI is dead we must move our CI pipeline to GitHub Actions.

I've literally never used, or even looked into either option, so I've got no idea about it. (Brief googling looks like they went proprietary recently, so that's not great. 👎🏻)

If you wanna help you can draft the upgrade news

Yeah, I can take care of that. Should be easy. 😉

I'll get started on that in a little bit. Do you have a time frame for when you think you'll be ready with 3.0? Just a rough idea, eg, "tonight", "this week", or "later on". For my own fire-lighting, ass-kicking purposes I mean. 😂

mayamcdougall commented 2 years ago

Writing a note about how YAML now requires strings that start with % to be quoted and how that effects Pico users (eg urls starting with %base_url%, etc).

Then I realized my example was one of the things needing to be fixed.

https://github.com/picocms/Pico/blob/master/content-sample/_meta.md

So mentioning it here so we don't forget to check that.

mayamcdougall commented 2 years ago

For the parsedown reversion, do you have any specific examples of what to be on the lookout for? In the old update post, you only mention issues caused by "non-standard markup", but never go into detail.

(I see you were contributing over there at one point. I stumbled across it while looking for changes, lol.)

Or should it just be a general, "the version has changed so make sure to recheck that your content files are still rendering correctly" sort of thing?

mayamcdougall commented 2 years ago

https://github.com/picocms/picocms.github.io/pull/54

This is what I've got so far. No need to merge yet unless you think I got it perfect in one go, lol. 😂

Just let me know what you want changed.

It's up on GitHub Pages for now, but I'll be switching GH Pages back to my Docs Rewrite branch once we're done. 😉

mayamcdougall commented 2 years ago

I've been testing some of the themes against the "Pico 3.0-alpha" build.

I'm up to the letter "D" so far.

I'm starting to see the rationale behind tagging these with some sort of "verified" date. 🤦🏻‍♀️

Still not gonna do it. But I am starting to think that a few of these themes shouldn't make the cut.

I'm discovering a lot more bugs this time around. Not 3.0 bugs either, but 2.0 ones or just things that were otherwise poor coding or bad practices.

So far the only 3.0 bug was on Astral, which is mine. Twig changed divisibleby(x) to divisible by(x). No big deal... though I'm seriously bothered by the fact that it has a space now. It's still a function, not a keyword... but it has a space. 😣

WHY?

*ahem*

But anyway... I fully expect that by the time I've tested everything, it'll only be my work with 3.0 bugs.

Because I would be the one to use obscure Twig functions, wouldn't I? 😂

I'm 100% expecting Notepaper to break, but I haven't gotten there yet. Maybe that'll finally motivate me to rewrite it. 😒

I'm also taking notes while I go though, for future Theme tagging (R2G, etc). 😉

mayamcdougall commented 2 years ago

So, it wasn't until that ☝🏻 issue was opened that I realized the alpha build was only using Twig 2 and not 3. Haven't done any testing since, but I've still got my test environment set up (with all the themes I've tested so far, and their associated files).

Trying to throw together a Pico + Twig 3 environment, and I'm already met with a big moment of Oh nooooooo...:

Unexpected token "name" of value "if" ("end of statement block" expected).

And in the Twig Docs:

Adding an if condition on a for tag is deprecated

So... yeah. That'll break like, just about everything. Just on its own too. 🤦🏻‍♀️

Didn't know that was gonna happen. Guess I'd better get to work. P=

Edit: Protip: \{% for .* if .* %\} Seems like it'll find those conditional loops pretty easily with a RegEx search. Haven't put it to the test yet, but it seems to work as intended. 😉

PhrozenByte commented 2 years ago

Here we go... :rocket: :+1:

Sorry for the late response, but I didn't want to answer until this was finished - and it took me longer than expected... :unamused: Anyway, the CI pipeline is back online, even though currently not working here because there are some GitHub repo config settings pending, but it does work both locally and on my fork.

You can give it a try: Simply run ./build/build.sh locally.

Making this work locally was a major task, but GitHub Actions allows us to remove a whole lot of workaround and helper scripts we used to require on Travis CI. Also see https://github.com/PhrozenByte/Pico/actions/runs/1907606936 and https://github.com/PhrozenByte/Pico/releases/tag/v3.0.0-alpha.3 (no official release, it's just for testing).

There are just three more things to do: (1) Code-wise there are some smaller code changes pending (including the bugs you opened some time ago), but no big issues here. (2) Pico 3.0 needs testing, most notably PicoDeprecated and Pico CMS for Nextcloud. (3) Last but not least the upgrade docs.

Thanks for your work on the upgrade docs! :heart: I didn't review your draft yet, just took a quick look. It's too late for today, but I'll likely find some time next weekend :+1:

I'll get started on that in a little bit. Do you have a time frame for when you think you'll be ready with 3.0? Just a rough idea, eg, "tonight", "this week", or "later on". For my own fire-lighting, ass-kicking purposes I mean. :joy:

It will surely take a few more weeks. I don't want to publish v3.0.0 right away, we should release a beta first and give people 2+ weeks for testing first. Besides, there's still some work to do (see above).

If I can help it, I don't like to leave questions on the Issue tracker unanswered... even if I don't actually have an answer. Sometimes you answer comments right away... and sometimes it takes you a week, lol, and I don't like leaving people in limbo in the meantime.

Just to explain this: I made the decision that I need to better "economize" with the little time I have for Pico. I can either work on Pico's code, or give extensive support, hardly both. Even though I try to answer any valid question and give at least some quick advice, I decided that I no longer want to do the questioner's job. People need to do their own research and try stuff for themselves. There are basically two possibilities why I don't answer right away: (1) I looked at it and I can't answer it within a few seconds in-between other work - so it's a matter of time; (2) I believe that I already gave enough advice. The latter includes people asking for stuff I believe is no matter of Pico, like webserver config. I still give quick hints, but these projects have their own support channels. The only reason I followed up on the latest issues was because I'll surely always answer your questions :+1: (even though not necessarily right away, there's still the time issue :see_no_evil:).

Anyway, please don't read this as some sort of criticism on how you handle things. I truly :heart: and admire the heart and soul you put into answering all questions :+1: I just wanted to explain myself here.

For the parsedown reversion, do you have any specific examples of what to be on the lookout for? In the old update post, you only mention issues caused by "non-standard markup", but never go into detail.

It's the same as before, just the other way round (i.e. we're going back to what we had before). So I don't expect any major issues from Parsedown, we should just mention it.

Still not gonna do it. But I am starting to think that a few of these themes shouldn't make the cut.

That's your métier, so I'm fine with whatever you decide :+1:

I realized the alpha build was only using Twig 2 and not 3

Yes :see_no_evil: From my experience while developing this, I'd say that Symfony YAML now requiring to quote values starting with a % (like Logo: %theme_url%/img/logo.svg), and Twig removing the {% for … if … %} syntax, are the two major issues of Pico 3.0. I know, this is bad :unamused: But we don't really have a choice, Twig 2 is end-of-life, too. If we don't update to Twig 3 we will likely run into similar issues soon.

mayamcdougall commented 2 years ago

Sorry for the late response, but I didn't want to answer until this was finished

It's okay, I've had my own testing instance that I cobbled together off the various 3.0 branches. 😂

I overwhelmed myself a little working on the Themes at first, so I've been taking it slower this week. It's not difficult, just time consuming. 😅

I made the decision that I need to better "economize" with the little time I have for Pico. / Anyway, please don't read this as some sort of criticism on how you handle things.

Don't worry, I get it. ❤️

Heck, I get overwhelmed with it sometimes and I don't even have that many other obligations. It's mostly just awkward at times. When I have to be like "Yep, idk when he'll be by to answer. Could be in 5 minutes, could be 5 days. 😅". No worries though, lol. Besides, it sounds like we're still among the faster turnaround times on GitHub. The impression I've gotten from a few issues has been "It's okay, I expected to be waiting for weeks." 😂

I truly ❤️ and admire the heart and soul you put into answering all questions.

Thanks. 😜

As I said recently on that crazy long conversation thread you unsubscribed from*:

I like helping people. One reason I provide Pico tech support here is because it's one of the few things I do have. I'm not the most knowledgeable. I find it kind of laughable that I'm often the main person answering questions on here and I don't know a scrap of PHP. Talk about imposter syndrome. 😅

But what keeps me doing it is that, despite not being the best, and despite the imposter syndrome... I'm still the one who can help them. It's something I can do. It's a difference that I can make. And often, I'm the only one who can. If someone's going to provide help... it's me. And that feeling of being the person who can make a difference keeps me motivated.

(* Just describing it that way to avoid linking/tagging. It's not remotely relevant to the actual discussion here, so I at least try not to pollute the repo with unnecessary links, etc. Also, didn't realize it was a two-paragraph quote when I decided to mention it... 😅)

So I don't expect any major issues from Parsedown, we should just mention it.

It's mentioned. That's about all I could say on it though, since as far as I can tell, the only changes are obscure bug fixes, edge cases, and such.

That's your métier, so I'm fine with whatever you decide 👍

Should probably have a proper discussion on it at some point, but the overview is this: We've got a few themes that are really more of frameworks than Themes (Boney, Bootstrap, Bulma, etc). But, like everything else, they've never been updated. Bootstrap, for example, is based on Bootstrap 3.0.

It's probably more a naming issue I have with them, as some of them do try to actually theme... they're just un-creatively named after framework they used, and I feel that gives the wrong impression. And on the opposite side, we have specifically themes like "Boney" and "Default Blog", that attempt to recreate the Default Theme, but with different frameworks or capabilities. I feel like that dilutes things a little. I wouldn't want users mistaking these for Official, or mistaking them for being based on the current codebase of the Default Theme. Maybe I'll just see about pushing some new name / color choices when I eventually PR them. 🤔

Anyway, that's already more than I meant to summarize here. 😒

I'd say that Symfony YAML now requiring to quote values starting with a % (like Logo: %theme_url%/img/logo.svg), and Twig removing the {% for … if … %} syntax, are the two major issues of Pico 3.0.

I wrote the Upgrade doc before testing Twig 3, but I definitely plan to point out that Twig change (and the YAML issue is already in there).

I did have the realization though: So what you really mean is, every Theme that's ever followed our instruction to borrow from the Default Theme will have issues? 🤦🏻‍♀️

If we don't update to Twig 3 we will likely run into similar issues soon.

Better to get the breaking done all at once. I'm not worried about the Theme breakage, and fortunately it sounds like there won't actually be any major Plugin incompatibility, so that's good.

It's also good that Pico doesn't offer any kind of auto-updating, so nothing's going to break without warning. As far as breaking updates goes, it should be pretty tame. The biggest issue is going to be everyone who's created or customized their own Theme. But that should hopefully mean that they have the know-how to sort out their own issues, especially if there's a warning upfront in the upgrade doc about what to expect.

I know that's having way too much faith in people, but oh well. We'll never actually hear about the amount of successful upgrades, only the failed ones. 😂

mayamcdougall commented 2 years ago

Ooo, some "art". lol. 😉👍🏻

Feels like a good time to mention that I also noticed the credit you added to yourself at the bottom of the Default Theme. 😉

Very well deserved, lol. I don't have any issue with it, I just noticed it a while back and wanted to be like "Aha, I see what you did there!". 😂

PhrozenByte commented 2 years ago

"CI is ready" was a bit premature, we kinda had a little chicken-and-egg situation with automatically building Pico and PicoDeprecated: Pico depends on PicoDeprecated to build, and PicoDeprecated depends on Pico to build. Fixed with 60d0f54. Builds might still fail if tags aren't pushed at the same time, but that's no big issue because one can simply manually start the workflow another time, check the result and then manually push a new release with make publish. Also see 81c2172

I overwhelmed myself a little working on the Themes at first, so I've been taking it slower this week. It's not difficult, just time consuming. sweat_smile

No worries, it isn't ready for release yet anyway :wink:

Heck, I get overwhelmed with it sometimes and I don't even have that many other obligations. It's mostly just awkward at times.

:heart: :+1:

Should probably have a proper discussion on it at some point, but the overview is this: We've got a few themes that are really more of frameworks than Themes (Boney, Bootstrap, Bulma, etc). But, like everything else, they've never been updated. Bootstrap, for example, is based on Bootstrap 3.0.

If it's this old and you can't reach anyone to inform the dev that the theme needs an update, we should remove it. I'm fine with removing more-or-less broken, or heavily outdated themes (and plugins, even though we didn't merge the wiki yet) which are no longer supported by their respective devs. You shouldn't feel obligated to do their work for them, if they don't want to update their themes, simply remove them.

I did have the realization though: So what you really mean is, every Theme that's ever followed our instruction to borrow from the Default Theme will have issues? 🤦🏻‍♀️

Unfortunately yes :unamused:

It's also good that Pico doesn't offer any kind of auto-updating, so nothing's going to break without warning. As far as breaking updates goes, it should be pretty tame. The biggest issue is going to be everyone who's created or customized their own Theme.

So, everyone :laughing: But yes, it shouldn't be a big issue for most users. I assume that a lot users will stick to Pico 2.1 at first, at least until their respective web hoster drops PHP 7 support. The biggest issue is that we likely loose a lot (abandoned) themes. However, personally I don't value abandonware much :wink:

Ooo, some "art". lol. wink👍🏻

Feels like a good time to mention that I also noticed the credit you added to yourself at the bottom of the Default Theme. wink

:wink:

picocms/picocms.github.io#54

This is what I've got so far. No need to merge yet unless you think I got it perfect in one go, lol. joy

Just let me know what you want changed.

It's up on GitHub Pages for now, but I'll be switching GH Pages back to my Docs Rewrite branch once we're done. wink

I'll review the changes there.