Add documentation and plugin notice about the end of the plugin version

[Levdbas]

Related:

• Timber 2.0 and the plugin version #2794

Work in progress

This is a first version of this PR where I would like to have input from the core team: @gchtr , @nlemoine and @jarednova . Could you have a look at the wording of the notices in the .txt, .md file? Is that what we want to communicate? Please change/complete my suggested texts and notifications where necessary so that we can release this.

Example of the plugin notice as currently commited

TODO's

• Fill the links in the code changes
• test the upgrade guide with a minimal theme and latest WordPress version
• Release a plugin version with the new code changes.

Issue

We are not going to release a plugin version of Timber anymore. We think that a lot of people will be stuck on the plugin version of Timber 1. With a install base of 50.000+ installations we are talking about a lot of people.

Solution

Let's inform Timber users about the upcoming end of the Timber plugin and help them with extra guides on how to switch to the Composer based (1.x) version.

Impact

Minimal on the codebase. This PR adds an inline plugin notification as the only code change.

Usage Changes

See the whole guide :)

Considerations

• I made a docs/getting-started/switch-to-composer.md guide. Is this the proper location?
• See the plugin notification I currently created. Is this the way we want to notify the plugin users about this change
• Is the switch-to-composer guide good enough?

Testing

No

[Levdbas]

Thank you for the feedback @jrathert, I'll pick this up very soon.

[gchtr]

This is fantastic, @Levdbas. Thanks so much, I’m sure this will help so many people to make the switch.

I made a docs/getting-started/switch-to-composer.md guide. Is this the proper location?

Yes, this looks good to me!

See the plugin notification I currently created. Is this the way we want to notify the plugin users about this change

Yes, I would have done it like that.

Is the switch-to-composer guide good enough?

Oh yes it is.

Thanks also to @jrathert for taking the time to read through this as someone who hasn’t a lot of experience with Composer 🙌.

[Levdbas]

Hi @jrathert and @gchtr, thanks for all the suggestions. I think I added them all and fixed up a final few todos as well. Maybe lets have one more pass at this?

[jrathert]

Hi @Levdbas - I added a few suggestions (some of the last changes were actually erroneous, I think). Thanks!

[jrathert]

Maybe lets have one more pass at this?

@Levdbas , thanks for the hard work (I am not only new to PHP, Twig, Timber and Composer, but also not too "github-savy" yet, but I keep on learning - I tried to add a few smaller changes/fixes as a review, hope it worked... ;-))

One thing that came to my mind when reading #2804: We always say we drop support for the plugin version of Timber (v1, needless to say). But will we still support the Composer-version of Timber v1? E.g., are there any plans/decision re: updating the code of v1 to make it PHP 8.2-friendlier at least (see #2793)?

Because I fear if we only tell people now to switch to the Composer version, they might feel safe re: PHP 8.2 as well, and maybe miss that they need to upgrade/change something one more time.

[Levdbas]

Good catches @jrathert! VScode directly imports PR comments for me but sometimes messes up the line comments... So I end up applying changes twice sometimes. Good to have an extra set of eyes on this! Much appreciated!

And regarding the support of the Composer Timber v1 version. I am pretty sure we are not going to actively update it anymore. So to make it compatible with PHP 8.2 would be out of scope as well.

Going though the documentation of this PR and already existing documentation, how would you suggest to communicate that as well? @gchtr , can you chime in on this as well?

[nlemoine]

Great work @Levdbas !

[jarednova]

This is looking good @Levdbas! Can you tag me when this is merged and ready for deployment to wp.org? Also happy to invite your wp.org user name if you're comfortable inside their SVN environment

[Levdbas]

I think we are good to go here! Although I have my own plugin in the .org repo, to say that I am comfortable with the SVN stuff, not really... 👯

The path forward would be:

1. Merge PR and maybe directly docs: updated plugin support part #2805 as well
2. Deploy new version of the docs
3. Check if the links work as intended.
4. Release new plugin version, while at it, maybe update the "tested up to" version as well?
5. The first two steps of this issue: Timber 2.0 and the plugin version #2794 @jarednova

[jarednova]

This looks great! I just adjusted the emphasis on some of the language at top (emphasizing Composer as the supported method) and tightening the formatting a bit

[jarednova]

@Levdbas I feel like you have the best view into sequencing of how we merge this (#2800), #2805 and #2794. Could you proceed with merging this into master when you have the necessary input and dependencies?

Once merged, please create a 1.x release checklist ...

https://github.com/timber/timber/issues/new?assignees=&labels=&projects=&template=release_checklist_1x.md

That will be my cue that things are ready for SVN hell delight!

[gchtr]

And regarding the support of the Composer Timber v1 version. I am pretty sure we are not going to actively update it anymore. So to make it compatible with PHP 8.2 would be out of scope as well.

Going though the documentation of this PR and already existing documentation, how would you suggest to communicate that as well? @gchtr , can you chime in on this as well?

I’d say at the moment, we won’t maintain the 1.x version anymore than really necessary.

The path forward would be:

1. Merge PR and maybe directly docs: updated plugin support part #2805 as well
2. Deploy new version of the docs

I have an addition to point 2 in this list: We need to merge this into 2.x as well before we can deploy the docs. Because the docs are built against the 2.x branch.

@Levdbas I’ll let you merge this when you feel that this is ready. From my side, this looks all good. After merging this PR, I can see that we can merge it into 2.x as well and publish a new version of the docs.

[Levdbas]

Alright @gchtr , Its merged! So you will merge the changes made to the MD files into the 2.x branch?

[aevansgit]

I'm using Timber v1.23 on a site that we're planning to replace with a new build but not until June or July 2024. Do you think I'll be able to get away with leaving as is?

[Levdbas]

Hi @aevansgit , are you using the plugin version? If so, you could try to migrate to the composer based version of 1.23. This way you will be able to receive one final update for the 1.x branch which will improve compatibility with PHP 8.1.

See https://timber.github.io/docs/v1/getting-started/switch-to-composer/