Commit a mermaid version of the core release cycle diagram to core

Looks nice and outdated pic is confusing

Having security coverage make more sense, thank you

Image appears slightly blurry in the preview but opens crystal clear.

Though wonder if core is the place for this ticket?

That for working on this!

Looks nice and outdated pic is confusing

For some background, the images on this page were originally designed as and meant to be a examples only. They were never meant to have current dates or version numbers. And there was text on the page to explain that. The current dates information should be in one place, at Drupal core release cycle.

What I've been (slowly) working towards is generic, overview of the process information on the Overview page and the details on Drupal core release cycle. This is similar to Symfony release pages. This work was on hold waiting for #3238652: [policy] Decide how long major Drupal versions should be supported and #3361260: [policy, no patch] Adopt a regular two year release cadence for major releases. I have been thinking there could be two images, a generic one and a specific one where the specific one is on Drupal core release cycle page and regularly updated as dates change.

Looking at the image it is hard to figure out the release month of, say, 10.3. It also shows 10.4 and there has been no decision that there will be a 10.4 release. If this is an example, that is fine, but the sentence explaining that it is an example has been removed. I am confused.

What would help is to make it obvious that we use a 6 month cycle. That means the months should be just June and Dec. But, there is a possibility of a September major release so maybe the 4 quarters would make sense, Mar/Jun/Sep/Dec? And it should span a major release to show the length of time a release is supported.

Other things I prefer is the releases down the left hand side, similar to https://symfony.com/releases. And like the symfony example, can we see what this looks like without the text in each row and a key to explain the color usage.

Shouldn't Minor release development and preparation also be updated to keep the same design? Is the type and time for the different tasks still correct?

I do wonder if this image is still needed. I expect it was helpful when it was created but surely most developers understand an alpha/beta/rc workflow. What do you think? If the image is kept my first though is that it should have week granularity to show the details that in the text.

Finally, I have restored the sentence on the Overview page about the release numbers being an example because the decision has not yet been made about a 10.4 release.

I am also tagging for release manager review.

@ressa, thanks again.

Since this is working with release info pages and dates, it can stay in the core issue queue.

I like the look of #14 and think it's a good improvement in general.

If we use full HTML for the documentation page, we can use embed the SVG inline, that way release versions and dates could be edited along with the page rather than even needing to update the file (unless we tweak the actual design). It limits how many people can edit the page but this is not one that gets loads of changes except right now.

I think we should consider changing 'Supported version' to 'Bugfixes', because with #3238652: [policy] Decide how long major Drupal versions should be supported we're also introducing the concepts of supported/maintenance/LTS for minor releases on the old branch when a new major comes out.

Would also change 'development version' to 'pre-release' maybe since that closer matches that period, it's the development version 4-6 months earlier than alphas start.

These graphs look visually so much better than what we have with google drawings :) On the other hand security support does not seem to be reflected? @catch suggested "consider changing 'Supported version' to 'Bugfixes'", not to change security coverage to bugfixes, which is incorrect.

There are two ways we can embed SVGs now:

1. Put the SVG in a git repo somewhere on Drupal.org, then embed it using img tags. This means the workflow for changing the image would be an MR.

2. Embed the SVG directly in the HTML, this requires full HTML so would make the page editable by many less people.

Both of these are barriers to changing the image, but there are also barriers to changing the image now. I kind of like the idea of it living in a git repo.

Curious how come D9 only went to .5 and D10 is going to .5 but D11 is going to .7 ?

So since this is for a drupal.org page wonder if it belongs in this project instead. If I'm wrong please move back.

This does need to remain in the core issue queue, it is specific to core and not other Drupal projects. The documentation for Drupal core development policies and practices, which includes the release pages, is separate from the Document project page.

So what's next step needed here?

GitLab md files support mermaid syntax out of the box, and among them, Gantt syntax: https://mermaid.js.org/syntax/gantt.html

Maybe we can have an actual md file in core with this information. I'll try to make a POC that can be modified by anyone interested.

Example from the above comment (copy/paste from one of the examples):
- View file: https://git.drupalcode.org/issue/drupal-3399348/-/blob/3399348-svg-templ...
- View code: https://git.drupalcode.org/project/drupal/-/merge_requests/5897/diffs

Note that the image generated is an SVG.

I don't want to derail this issue, so if this is not appropriate for this issue, just ignore.
If it's something that might be good, then we will just need to tweak the markdown file as needed.

I adapted the MR to contain real data that was provided by @kimb0 a while ago in slack and fell through the cracks.

Result: https://git.drupalcode.org/issue/drupal-3399348/-/blob/3399348-svg-templ...

If we want to have this be part of Drupal core, I think this MR might be ready for review.

One idea I had was starting the new major version at the top of the diagram each time (would mean removing the version label from the left)

This kind of thing:

-          -
 -          -
   -          -

Not entirely sure how to build what @catch suggested.

Since we're playing with themes/colors, we can set the colors we want too (throwing some Drupal-blue into the theme):

https://git.drupalcode.org/issue/drupal-3399348/-/blob/3399348-svg-templ...

The only way to display these "pills" in the same line is by using the compact mode that you also tried (at least from what I've been reading), and I'm not sure about how much control we have over them (about which one goes where).

It seems like you can't control which one to start from.

You can tweak tickInterval 1month and that'll show all months.
I tried and it doesn't look too good:

But it seems like it always starts with January.
So setting the value to 2 or 3 won't work either:
- 2: Jan, Mar, May, Jul...
- 3: Jan, Apr, Jul, Oct...

I tried as shown in the image and reverted the change.

Note that you can go to https://mermaid.live and tried the code of this MR to play with it as needed.

That's great. Do they need to show June and December? The dates should still be listed in the tables. How many releases need to be in the chart?

I would only expect the +/-3 months of releases. I could see showing the rest of the D10 release cycle.

Would we say this is ready for release manager?

I like the idea of using mermaid for this, and maybe having a file in the core repo. Not sure which of the two diagrams I prefer although the compact one feels easier to scan.

Ok, let's try that in the MR then.

Changed the MR based on #42 compact mode.
You can view it here: https://git.drupalcode.org/issue/drupal-3399348/-/blob/3399348-svg-templ...

Not sure if I did something wrong but applied the MR and viewing the file I still see just the code and not the markdown.

Edit

Using phpstorm which renders markdown

Back to Needs review I assume.

Still just seeing code

Have you tried this plugin? https://plugins.jetbrains.com/plugin/20146-mermaid . I have not, but maybe it can render it.

Ref: https://www.jetbrains.com/help/phpstorm/markdown.html#diagrams + https://www.jetbrains.com/help/writerside/mermaid-diagrams.html

using that plugin this is what I see

I only used https://mermaid.live, and the result on Gitlab, not any local dev tools.

Same here. I think that seeing just the code in the editor is fine.

In order to render it locally, we'll need a plugin in the editor.

Maybe we can add a note inside the md file above or below the graph saying that mermaid is supported by GitLab and that to view it locally you'd need a plugin, but not sure that it is needed. ie: even if markdown viewer is very common in most editors, it's not always present.

In gitlab it looks perfect.

I think a link to the gitlab page would work.

Link added. The link points to the 11.x page where the file does not exist yet.
https://git.drupalcode.org/issue/drupal-3399348/-/blob/3399348-svg-templ...

I think this looks good! And good timing

This needs an issue summary update, both of the examples look outdated to me compared to the version in the MR. i.e. it's still linking to mermaid.live but should probably be https://git.drupalcode.org/issue/drupal-3399348/-/blob/3399348-svg-templ... ?, not sure whether the screenshot also needs to be updated.

One question I have is how we incorporate this into https://www.drupal.org/about/core/policies/core-release-cycles/release-p... - I think we would still have to either copy and paste the svg code into full HTML or a file then embed it, both of which require high level permissions on d.o, or screenshot it. These are not significant issues compared to the current situation where we have to regenerate a png but needs thinking about. It would be great if we could embed the svg from the .md file directly but that seems unlikely to be supported.

Overall this is very close to the overall structure of the current image, just easier to update. I did have ideas about trying to make it more compact, but seems like they don't work in practice and I didn't have a proper go at implementing myself either, so for me what's in the current MR seems like a good plan.

We can download a PNG image from the mermaid.live page. Maybe we can just document it in this same file?
I'll add it to see if we wanted, otherwise we can discard it.

I added the instructions to download the image, see here: https://git.drupalcode.org/issue/drupal-3399348/-/blob/3399348-svg-templ...

I also update the issue summary. Not sure if I should remove the tag and bring it back to RTBC.

iS appears to be updated in #63

Re-titling.

I am very in favour of this issue but still a bit stuck on how to embed it on Drupal.org, I think the answer is we can't and need to use it as an svg generator still, but maybe long term we can find a way to rework the docs to allow this.

Committed and pushed f31a2704ea to 11.x and 3c52d04cdb to 10.3.x. Thanks!

@catch pointed out this still has the "needs release manager review" tag and so I committed it prematurely.

🖐 I'm putting my hand up for issue credit for this one as I wrote the original mermaid that was posted to slack (see #34)

I have finally been able to look at this.

The first thing that I see is that the colors have changed. I think they should be the same as the existing colors. We should be continuing to follow the practice of green for fully support, yellow for maintenance and red for end of life used in the PHP community. See the links at the end of this comment. And more importantly the colors should agree with the Drupal sample release schedule.

The chart should also have a footer with something like, 'Dates are subject to change.' with a link to https://www.drupal.org/about/core/policies/core-release-cycles/schedule for the most up to date information.

I then applied the diff. The file is not a pleasant read in an editor. It is mostly a wall of code but I understand why it is that way. But I didn't even realize there was a section "Export graph as image' until I scrolled.

I then went to edit the mermaid file. The editor does not allow me to right-click and copy which is annoying. It is easy to copy the existing sections to add a new one. But it is clear to me that I need to read the mermaid docs to fully understand the format.

I think it is important that the chart includes a statement that the dates are subject to change. I searched a bit for that but didn't find anything. I hope someone else does find it.

And finally, the file name is 'releases' needs some thought. It could mean this is a file listing all releases. Right now I lean to 'releases calendar' which I found at https://symfony.com/releases.

• https://www.php.net/supported-versions.php
• https://symfony.com/releases
• https://phpunit.de/supported-versions.html

The current color scheme was made to match a bit more Drupal (and Drupal.org) colors. I will change it to your suggested one.

I think it is important that the chart includes a statement that the dates are subject to change. I searched a bit for that but didn't find anything. I hope someone else does find it.

The main file is still markdown, so we can add things before and after the graph easily.

I'm working on your suggestions at the moment.

I think that all feedback from @quietone at #74 has been addressed.
Result: https://git.drupalcode.org/issue/drupal-3399348/-/blob/3399348-svg-templ...

Back to needs review.

Appears to be a random JS test failure, reran and all green.

Believe feedback and questions are answered. Link in 76 still looks good

@fjgarlin, thanks for the updates.

As stated in #74, I still think we should be using the existing color pattern current shown at, https://www.drupal.org/about/core/policies/core-release-cycles/release-p....

Why has the latest version introduce coloring some rows in an alternating pattern. This is not something done on the related project linked to in #74. Personally, i find it very distracting. What is the purpose of this?

No purpose, it's just a default. It seems to be by mermaid based on the chosen colors.

The previous version also had it, it was just blue: https://www.drupal.org/files/issues/2024-02-23/mermaid-diagram-2024-02-2...

I don't know how much control of it do we have to be honest. I can play with it a bit and see if I find any option for this,

I tried to remove the background stripes completely, I couldn't.

I tried pretty much all color/background related variables from here https://mermaid.js.org/config/theming.html#theme-variables and there are some colors that are just generated and cannot be changed.

So the closest, less-distracting thing that I could get was a green/white striping (it goes green-derived-from-primaryColor, white, tertiaryColor, white, and then repeat). We have control over the tertiaryColor, but that's about it.

New version: https://git.drupalcode.org/issue/drupal-3399348/-/blob/3399348-svg-templ...

@fjgarlin, thanks for explaining the row coloring.

Is it possible to use a non green or yellow color for the alternating rows so it doesn't seem associated with the data? Perhaps a light gray?

Still to address is the color scheme change mentioned in #74 and #78.

I managed to find an undocumented color property to be able to control three colors and try to match the coloring from here: https://www.drupal.org/about/core/policies/core-release-cycles/release-p...

See the latest version: https://git.drupalcode.org/issue/drupal-3399348/-/blob/3399348-svg-templ...

--

Is it possible to use a non green or yellow color for the alternating rows so it doesn't seem associated with the data? Perhaps a light gray?

The lighter green is derived from the primaryColor and cannot be made white or transparent as far as I know, so it cannot be changed to light gray without changing the primaryColor to light gray, which in turn would change the color of the "Support" pills.

Believe the color change has been addressed. Still rendering just fine for me.

@fjgarlin, thanks for continuing to adjust the diagram!

This new file currently duplicates information about end-of-life dates found in core/modules/update/src/ProjectSecurityData.php, meaning release managers would have to update this in two places every release.

Can we come up with a way to consolidate that, perhaps by refactoring ProjectSecurityData and using a script to generate the Markdown file?

Also, just a nitpick, but the filename should be RELEASE-CALENDAR.md, not RELEASES-CALENDAR.md. :)

Can we come up with a way to consolidate that, perhaps by refactoring ProjectSecurityData and using a script to generate the Markdown file?

What if we moved the relevant data to a YAML file? ProjectSecurityData.php could load it from there and we could create a script to modify the markdown file. I believe as things are currently configured it would still have to be run manually when those dates change. I'd love to be told I am wrong though!

@xjm (or anybody that knows the answer really) - I fail to see the connection between the data in that php file and the data displayed in this calendar.

I’m trying to think of a programmatic way of using the constants but i don’t see overlap in versions nor dates. Maybe I don’t know enough about that other file.

Also, if you see the code of the graph, it’s going to be real hard to find a way to automate things. Right now it seems very handcrafted.

I think we’d need to know more about the other file to be able to address the feedback. Also, should we do that here (based on the scope of the issue) or maybe commit this and then do a follow up?

Some clarification would be great.

I think #87 is a great suggestion.

@fjgarlin The dates are the same dates; they are tied exactly to the expected release, end of bugfix support, and end of security support dates for the expected minor releases. You just don't see the connection in the current values because we have not set an end of life for Drupal 10 yet. Every time we do a release outside the most basic schedule and every time we issue a new major, we will have to update both these sets of dates. It will be extremely easy for them to get out of sync or show wrong information unless we abstract it, and that would add yet more tedious manual overhead for release managers.

For example, there's a reasonably strong chance 11.0.0 will come out in August, and a possibility that 10.5 will receive security support for more than six months. Both places would need to be updated in both these scenarios. (The UI should still start issuing warnings about using 11.0.0 after mid-December, for the existing file, and its support bar should only be 4-ish months long until that same mid-December date, for the new file).

Having a cleaner way to enter the data so it can be parsed and exported to both places, plus adding a script to do so, would reduce the maintenance overhead of adding this.

Thanks!

Saving some credits.

Ok, so, if I understand this right, we'd have a yaml file with raw information (will suggest a format at the end of the comment), and from this file we'd generate the constants on \Drupal\update\ProjectSecurityData (just the constants and the logic to read those obviously), and we'd generate the mermaid file from the information on that file too, right?

Will a format like this work? (I just included a few entries)

'10.2':
  Security:
    start: YYYY-mm-dd
    end: YYYY-mm-dd
    end_warning: YYYY-mm-dd
'10.3':
  Support:
    start: YYYY-mm-dd
    end: YYYY-mm-dd
  Security:
    start: YYYY-mm-dd
    end: YYYY-mm-dd
    end_warning: YYYY-mm-dd
'10.4':
  Maintenance:
    start: YYYY-mm-dd
    end: YYYY-mm-dd
  Security:
    start: YYYY-mm-dd
    end: YYYY-mm-dd
    end_warning: YYYY-mm-dd

For example, the above file (it's just truncated) would generate all the constant below (even if only some are needed):
- SECURITY_COVERAGE_END_DATE_10_2
- SECURITY_COVERAGE_ENDING_WARN_DATE_10_2
- SECURITY_COVERAGE_END_DATE_10_3
- SECURITY_COVERAGE_ENDING_WARN_DATE_10_3
- SECURITY_COVERAGE_END_DATE_10_4
- SECURITY_COVERAGE_ENDING_WARN_DATE_10_4

And then we'd somehow use that info to build the graph.

I still don't know how but I want to validate that the approach above is what is expected.

we'd have a yaml file with raw information (will suggest a format at the end of the comment), and from this file we'd generate the constants on \Drupal\update\ProjectSecurityData (just the constants and the logic to read those obviously)

That would work, but I would advocate for replacing the constants with methods that would load the data from the YAML file directly. That way, the only thing we need to generate manually (or ideally in a build step) would be the markdown file.

Yeah, they don’t need to be constants in the new implementation, i was mostly comparing them that way due to the current implementation. It’s probably easier with methods.

We won’t be able to update the file via CI but we can provide a script that will update it as @xjm suggested.

—

I’d like to have a green light on the approach above before starting, given that there was already a lot of back and forth and work on this issue (even RTBC several times) and we now need to build a whole different thing. I’m fine with this, I’d just like confirmation on the suggested approach (probably from @xjm) so we’re clear on the expectations too.

A script that will update it is good - we already have various core committer scripts for branching new releases.

I don't like the idea of generating the markdown file because that would make it hard to edit other aspects of it, but updating it based on the YAML file seems handy to me.

However it's @xjm who has maintained the release charts in the past, so as @fjgarlin said in #93, she's more likely to spot any flaws than me.

That proposed YAML format is nice and clean, +1.

I also agree with the proposal to deprecate the existing constants and replace them with methods as per #92. AFAIK this data is only ever displayed to administrators on status reports, so it's not in the critical path and loading them from yaml is fine.

So we would have in this issue:

1. The new yaml format.
2. A core script to write the YAML data to the markdown file, which we run to update it every time we update the scheduled dates.
3. Method additions to load the necessary dates from the YAML file and use them in the warning/error calculations.

And separate issues:

1. Deprecate the D9 constants in a separate issue (they should have been removed in 10.0.0 anyway; we just didn't have things to replace them with yet). (Logic related to constant magic-matching would still be deprecated in this issue.)
2. A script to update specific schedule entries in the YAML given input (we could integrate this into release tagging to allow the tagging script to optionally update release dates and EOL dates based on when exactly releases come out).
3. Possibly (not sure about what we'd want to do yet): Additional improvements that will somehow allow this to entirely replace the core release schedule handbook page, so we don't have to maintain the dates in two places.

NW to implement the new approach. Thanks!

Well that user is correct though?

Minor releases are supported for one year, but they're released every six months. So while you have one year to update from release x to release y, you need to plan to update every six months. The one year support just means that exactly when you do this relative to the release date is more flexible.

If you really, really wanted to avoid this, you could skip a minor release - so 11.2 -> 11.4, 11.4 -> 11.6, but that would mean timing site updates to more or less the day that 11.4 or 11.6 are released - otherwise if you miss that, 11.2 or 11.4 drops out of security support. We'd never advise sites to follow that pattern because it adds additional risk that they'd end up on an unsupported minor release.

Re pushing this issue, up until comment 85 this even went to RTBC and is a single file, easy to read and edit, But from comments 85 - 96 a whole new dynamic approach was requested, and it's not straightforward.

I don't think I have the time to tackle this, but anybody can take it.

Update links to good examples.