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

Looks nice and outdated pic is confusing

Thanks @andypost, do you think I should make "Minor release development and preparation" also?

I just see I switched the words for two blocks, here's an updated version.

Having security coverage make more sense, thank you

I ask because we should probably update both at the same time.

I made a fresh SVG version in Inkscape, aligned to a 1200px grid. I also swapped the font to Arial, something everyone has on their machine.

Arial bold is better, I think.

The black text on pink and yellow background might need a slight smoothing, to dark grey.

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

Though wonder if core is the place for this ticket?

Thanks @smustgrave, I added the diagram to the Overview of the release process → page. I am attaching the template SVG-file, with a .txt extension on that page and here for future updates.

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?

Here's the Minor release development and preparation → . Are the dates correct?

@smustgrave: Feel free to move the issue, if you think there is a better place for it.

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 🌱 [policy] Decide how long major Drupal versions should be supported Needs review and 🌱 [policy, no patch] Adopt a regular two year release cadence for major releases Fixed . 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.

You're welcome @quietone :-)

I removed the "This is an example text", thanks for restoring it.

What would help is to make it obvious that we use a 6 month cycle.

I agree, and was a bit puzzled by the May/Dec cycle in the two original charts. Perhaps they should have been June/Dec?

... there is a possibility of a September major release so maybe the 4 quarters would make sense, Mar/Jun/Sep/Dec?
[...]
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.

I agree, it looks better with the version to the left. Though in this first sketch, I tried with just June+Dec, but I can add "Mar" and "Sep", if you think? I used the dates from the 🌱 [policy] Decide how long major Drupal versions should be supported Needs review for Drupal 11, to align with actual proposed dates.

I do wonder if ["Minor release development and preparation"] image is still needed. I expect it was helpful when it was created but surely most developers understand an alpha/beta/rc workflow.

Yes, you're right, developers probably know this, so it's probably not necessary.

Reduced space between versions in left side and lanes, I'll update the example in previous comment.

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 🌱 [policy] Decide how long major Drupal versions should be supported Needs review 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.

Using inline SVG's would be nice, for much easier updating. I updated the chart with your suggestions, which do make more sense, and here it is.

@xjm: I don't see the advantage of SVGs over the existing Google Drawings until we can actually embed SVGs. In both cases the image has to be edited to reposition bars, update text, etc., then exported to a PNG and embedded. Any advantage an SVG has over Google Drawings for updating is lost by the fact that the template SVG has to be downloaded and edited with special software and then re-uploaded as both original file and exported version, without being able to share the canonical version for anyone to edit or comment.

I would prefer to use the format we've used for years instead of this new embed. We can replace all the diagrams everywhere (not just one or another) with proper actual SVGs if/when d.o allows users with access to Full HTML to embed them (or ditto for JS embeds with the JS diagram tool someone created for us awhile back).

I also prefer to use a graphic that doesn't need to be updated every six months. This is part of why the minor prep section uses examples for very old versions.

From Discuss Overview of the release process → .

Until SVGs can be embedded, a SVG-template is not relevant, so closing this issue.

@effulgentsia mentioned in #3238652-123: [policy] Decide how long major Drupal versions should be supported → that it would be great to use something like Apexcharts "... to generate an SVG given an input array of versions and dates."

The Timeline Charts > Multiple series – Group rows is probably the one to use, so here's a proof of concept I made, which can be expanded on.

Perhaps someone with more JavaScript skills can figure out how to force date labels to be "June 2024", "Dec 2024", etc. as well as other improvements? :-)

To see the interactive html-page, and the SVG it can export, download the files and remove the _.txt extension.

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.

Thanks @Gábor :) And you're right about the naming, I updated 'Supported version' to 'Bugfixes'. The 'Pre-release' category could be removed, if it adds too much clutter?

I added some more versions, and tried but failed to set the labels at the bottom to "Jun 2024", "Dec 2024", etc. It looks like a bit of JavaScript may be needed, see Datetime axis tickAmount issue and xaxis docs. Maybe someone can help with that?

Having the SVG in a Git repo and updating via MR sounds like a fine solution to me.

Some dates for D10 were wrong, here's an updated version, added in the Issue Summary.

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

That's a good question @smustgrave :)

It's because I based it on the chart from Release process overview > Sample release schedule →

→

This is an example. The exact schedule varies, and will be published on the Drupal core release schedule → .

I added it in the Issue Summary.

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

I don't want to derail this issue, so if this is not appropriate for this issue just ignore.

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.

Great find @fjgarlin! This solution certainly makes updating and adding dates much easier.

Months and lines

The question is which months to show at the bottom, but that can change, I think ... Like @quietone commented:

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.

Theming

The grey colors are a bit bland. It looks like Gitlab defaults to the neutral theme. I looked at the options with https://mermaid.live/, and maybe forest is the best? I have updated the MR, to test it.

Default theme, grey

Forest theme

What do you think?

More compact, possible?

As it is now, the diagram gets a bit tall, so it would be nice to have the minor versions on the same line, like the two 10.3 releases (10.3 support, 10.3 security). I tried Output in compact mode but that doesn't work ...

See also Multiple tasks on one line #1996.

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...

Looks good. Do you know if it is possible to define the months, and maybe show minor versions (like 10.3) on the same line? (See my comment https://www.drupal.org/project/drupal/issues/3399348#comment-15369925 📌 Template for Core release cycles diagram RTBC )

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).

I see some define each pill manually, setting x,y coordinates for each individually, but that kind of handheld approach defeats the purpose.

Do you know if the month lines can be set to for example June and December, which are the typical release months?

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.

Thanks for testing the options for months, it seems like it's not possible ...

I tried to create a version with minor releases in the same swim lane.

The downside is that the LTS-background as seen in the image in comment #37 is not possible:

But it didn't work too well I think, since the LTS-region is marked up as white. A user will think that the "LTS" in the image in comment #37 refers to the blue area below, not the white area above.

I am attaching both versions, in case we want to carry on with one or the other -- is it better with two branches?

PS: I see a typo in my new image: In the compact version, the second "12.1 Support" should be "12.1 Security" :) (fixed in the attached txt file)

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?

Thanks for pushing this forward @smustgrave, your Needs Review Queue Initiative → is a stroke of genius.

I updated the Issue Summary, adding outstanding decisions.

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.

Back to Needs review I assume.

Still just seeing code

Have you found a way to integrate https://github.com/mermaid-js/mermaid in PHPStorm @smustgrave? Because I only used https://mermaid.live, and the result on Gitlab, not any local dev tools.

@fjgarlin: Could you render the diagram locally?

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.

I'm not sure if we need a legend for blue/light blue/green (or if mermaid supports legends?).

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.

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 point out this still has the "needs release manager review" tag and so I committed it permaturely.

🖐 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

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 it will 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.

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!