Untangle branch confusion and document missing features in 3.x

Yikes, this is extremely confusing -- is the 2.x branch going to get deprecated? That's certainly the impression from the project page... is there an upgrade path from 2 to 3? Should anybody upgrade from 2 to 3?

I think the smarts incorporated in 2 are a big improvement over 1 -- if 3 is just about adding Drupal core compatibility I wonder why it didn't stay on the 1.x branch?

Almost seems like there should be two different modules.

I think clarifying this on the project page is pretty important so bumping to major.

I don't understand why you would tag 3.0.0 from the 8.x-1.x branch - but whats done is done - but the impact is crazy, as we are going to keep seeing v3 as a recommend update from composer and the available updates page.

If the 2.x branch will continue to be the path forward, maybe it needs to be deprecated, and open a v4 from the old v2?

Given the differing features from the 1.x to 3.x branch, the 3.0.0 version is effectively a downgrade. We're finding that moving to 3.0.0 can break some sites during updates.

I think we have to remove the recommended version from 3.0 and also, why would a module want to two separate feature-set maintained. Isn't it better for folks in 8.x-1.x to just upgrade to 2.x?

Additionally it is very confusing that the contributed module documentation points to settings not available in latest 3.0 branch. It was only my sharply justified brain ;) and memory from previous setups that made me wonder if I am on the right project installed or if there is some downgrading refactoring going on which is not reflected in the docs. Leading me to search issues and start reading this one and wondering if this branch confusion is related. So I tested and switching to the 2.x branch brings back the settings.

Just an example (and one of the main reasons why you should use this project over any other Block attribute alike ones at the moment): https://www.drupal.org/docs/contributed-modules/block-class/attributes

Updating to the latest branch leads to a loss of configuration in cases when an average user follows Drupal core notification and recommendation to update, since the custom attributes setting is not available no more.

I would even consider this "Critical" but I leave it up to others to decide. Since this is branch and project set up related there is sadly nothing issue contributors can do here without maintainers. Feel free to add me co-maintaining and correcting/update the issue and project page if time is limited.

Read across too quickly. Comment #4 is the missing confirmation I spoke about to consider "Critical" from other users. Considering that this project has 112,214 downloads counted. Change status accordingly.

Only correction of #4: The features are not only present in 1.x but also in 2.x as stated in my previous comment.

There seem to be a general release confusion going on which needs to by reviewed of some more experienced maintainers involved in this project: https://www.drupal.org/project/block_class/issues/3363340#comment-15799590

From my experience on projects I maintain or co-maintain, reason for such situation it is often a difference in strategy multiple maintainers have in mind or humble over in a rush. So maybe there is clarification between maintainers required. Also some decisions maybe should be discussed together before moving on.

IN case some readers humble over: #3467973: Moving from V2.0 to V3.0 I placed a warning over there too. This is all what I can do from my side here to prevent users falling into this issue.

I just released https://github.com/hanoii/composer-should-not - this is something that I had in mind for quite a bit.

What I think should happen is that the module maintainer should release a 4.x being just 2.x but with a higher version.

maintainer should release a 4.x being just 2.x but with a higher version

I can help on this

Context:

• I'm a maintainer
• However a little away from this project in the last months due to busy agenda on my other projects
• I wasn't the responsible for creating 3.x from 1.x
• Agreed that it can cause downgrades, as mentioned on #4
• So if you agree I can go ahead with suggestion #10 and release 4.x based on 2.x

+1 on this -- please make the 2.x version have a bigger number than the downgraded 3.x version!

+1 on this -- please make the 2.x version have a bigger number than the downgraded 3.x version!

Ok, I'm on it

As agreed, created 4.0.0 based on 2.x

FYI: Added a Matrix of compatibly and a guidance for the upgrade: https://www.drupal.org/project/block_class#matrix

Any feedbacks on this guideline feel free to let me know

Because there are no significant changes between 8.1.x and 3.0.x and zero changes between 2.0.x and 4.0.x it was not necessary to mark the source branches as "unsupported", leading to unneeded security confusion.

It’s expected. Only 3.0.x and 4.0.x are supported and no one will commit on 8.x-1.x or 2.0.x anymore

Details

• 3.0.x is based on 8.x-1.x
• 4.0.x is based on 2.0.x
• Only 3.0.x and 4.0.x will receive updates
• Old versions won’t receive new commits anymore
• Honestly I understand your point about the message of “unsupported” but it’s the truth
• I can’t mark the checkbox “Supported by Maintainers”
• Because is not true, since no one will update these branches anymore
• And If marks as “supported”, it would covers security policy
• So would be necessary overhead duplicating effort applying fixes on these old versions
• If someone needs to remove the message My recommendation is updating as mentioned on Matrix - Upgrade Guidance

If you are on 8.x-1.x: Upgrade to 3.0.x
If you are on 2.0.x: Upgrade to 4.0.x

I agree that 1.x and 2.0 marked as unsupported is the correct and best approach.

We're very sorry for all the confusion and potential issues the changes to the module's versions could have caused to your projects.

Major version changes are "bad" (not recommended) and should be avoided as much as possible (we know that now 😖), so this particular issue should not present itself again in the future, as long as we stick with minor version increments.

The Project page was also updated accordingly to provide more details on development branches 3.x and 4.x, see:
Should I use version 3 or 4?

The "Matrix of compatibility" added above at #15 was moved to a specific documentation page: Block Class Version compatibility, to which users get directed from the Project page.

Lastly, as a follow-up to this issue and an attempt to reconcile the different supported development branches of the module, the following ticket was created: #3556324: Merge 3.x and 4.x branches

We would certainly be glad to hear your comments, opinions or ideas on the options moving forward for the Block Class module. 👍
 

Since there has not been any activity on this issue for a year, it is safe to assume the documentation changes and creation of the 4.x branch should have fixed the problem initially reported.

Marking issue as Fixed, for now.

Any comments, advice, suggestions or code reviews would definitely be greatly appreciated! 👌

Feel free to let us know if you would have any questions or concerns on any aspects of the latest code changes or the module in general, we would surely be glad to hear your feedback. 😊
Thanks in advance!

Special thanks to @renatog for the quick efficient response handling this unfortunate situation! 🙏