Problem/Motivation
As mentioned in #2647824-29: [policy and patch] Determine what should go in CHANGELOG.txt for 8.x core releases, for the Drupal 8.4.x minor release, we're going to use a single collaborative process for drafting the core release notes in a markdown format. This will allow us to use the collaborative process we've used in the past for minor CHANGELOGs (see, for example, #2846830: Add changelog for Drupal 8.3.0) and reduce the duplication of effort and manual labor for creating release notes for Drupal.org.
Proposed resolution
Identify important features or improvements that have been committed to 8.4.x only. Make sure these issues are tagged with 8.4.0 release notes.
Add an entry describing the change. Use markdown to draft the release notes and organize the entries in sections. Example entries:
## Third-party library updates
* [Drupal's Symfony dependency has been updated from Symfony 2.8 to Symfony
3.2](https://www.drupal.org/node/2712647). This major version update is
necessary because Symfony 2.8 support will end around the release of Drupal
8.6.0 next year. [See the change record for information about Symfony 3 BC
breaks that affected Drupal core](https://www.drupal.org/node/2743809).
[Drupal 8 also requires Symfony 3.2.8](https://www.drupal.org/node/2871253)
because of a bug in Symfony 3.2.7.
* [zendframework/zend-diactoros has been updated from 1.3.10 to 1.4.0](https://www.drupal.org/node/2874817).Each entry should link the relevant issue. This both provides a way for users to learn more about the change, and allows us to parse the release notes and confirm that we've written entries for all the important changes. (So #2848192: Add issue #s to CHANGELOG.txt entries can be closed as a duplicate of this issue.)
For reference, here are the release notes and CHANGELOG from 8.3.0:
- 8.3.0 release notes: https://www.drupal.org/project/drupal/releases/8.3.0
- 8.3.0 changelog issue: #2846830: Add changelog for Drupal 8.3.0
Note: #2191525: [PP-1][policy, no patch] Extend Markdown coding standards to support API module (DOXYGEN) is open for Drupal markdown coding standards generally, and #1224506: Allow markdown on drupal.org comments (with a non-default markdown-tuned input format) is open to add support for Markdown on Drupal.org. However, for this release, the release managers will just use a third-party tool to convert this Markdown file into HTML that will be used for the body of the core release node.
Remaining tasks
Expand the stub patch with additional sections and entries.
| Comment | File | Size | Author |
|---|---|---|---|
| #93 | interdiff.txt | 2.05 KB | xjm |
| #93 | 2895685-92.patch | 7.95 KB | xjm |
| #91 | interdiff.txt | 1.35 KB | catch |
| #91 | create_release_notes-2895685-91.patch | 7.33 KB | catch |
| #90 | create_release_notes-2895685-90.patch | 7.41 KB | cilefen |
Comments
Comment #2
xjmHere's a better draft outline for the release notes with some tricky things explained (but most issues still missing). FWIW, I'm editing this in https://github.com/xjm/drupal_core_release/blob/master/templates/CHANGEL... (a github repository we use for automating release processes).
Comment #3
xjmComment #4
xjmThis adds the markdown format to the CHANGELOG file for now. We won't necessarily actually ship it this way; the past changelog is probably going to be removed and instead kept in a handbook page on d.o. However, I thought it would be easier to provide interdiffs this way.
Comment #5
xjmActually attaching the patch.
Comment #6
gnugetI'm new on this, the Upgrade of Jquery to 1.12 should be included in the release notes? #2809427: Update jQuery UI to 1.12
Comment #7
xjm@gnuget, yep for sure! I've added the "8.4.0 release notes" tag to that issue. Would you like to add an entry to the patch here for it under the third-party libraries section?
Comment #8
gnugetSure.
New patch attached.
Thanks!
Comment #9
xjmThanks @gnuget!
For IFE, @andrewmacpherson suggested we draw on #2888189: Update hook_help and DO docs for Inline Form Errors.
Comment #10
xjmAdding a couple more stub sections, and improving the sections on Media and Datetime Range.
Comment #11
xjmPhooey, named interdiff as a patch. Sorry testbot.
Comment #13
xjmA few more textual improvements for Media.
Comment #14
xjmHere's stub markdown for the issues that are already tagged but not yet included in the patch:
The script for this is in the core metrics repository: http://cgit.drupalcode.org/sandbox-xjm-core_metrics/tree/core_release/mi...
(For up-to-date data, someone with access must run the relevant query set on staging.)
Comment #15
mpdonadioI swore I saved this...
Minor tweak to the DTR section. Hoping to get a better DT and DTR REST UX in 8.5.x, with some additional validators and normalizers.
Comment #16
xjmThanks @mpdonadio!
We also should add a similar mention for media (from #2835767: Media + REST: comprehensive test coverage for Media + MediaType entity types). Probably:
Comment #17
xjmFor this issue:
[Drush 8.x doesn't install Drupal 8.4.x and Drush master doesn't install Drupal 8.3.x](https://www.drupal.org/node/2874827)It's already addressed by the first section of the release notes; we just need to link it.
Comment #18
prestonso commentedThis patch categorizes the issues from the stubs in #14 into their respective sections and directly addresses #16 and #17.
There is still a lot of work to be done here; I flagged any issues that will need additional prose with a prepended asterisk, and issues that remain open are prepended with "(open)". I did my best to categorize things correctly, but this might need additional review.
Hopping back on this tomorrow to bring in necessary prose about major changes and to refine further.
Comment #19
wim leersAs the REST maintainer, I figured it'd make sense for me to write something for that section. From what the patch looks like so far, that's at least what I thought needed to be done. For REST, several issues were in the wrong bucket. One in REST belonged in config DX (closest bucket being DX improvements). One in performance & scalability belonged in REST, as well as one in DX improvements.
I also went over #2852860: REST: top priorities for Drupal 8.4.x to ensure I didn't miss anything. I decided to also tag #2846554: Make the PathItem field type actually computed and auto-load stored aliases, #2853300: Standardize fatal error/exception handling: backtrace for all formats, not just HTML, #2847708: RPC endpoint to reset user password
Comment #20
wim leers@xjm asked me to add an entry for #2801777: Give users the option to prevent drupal from automatically marking unused files as temporary , which is the critical issue that introduced a stopgap solution to prevent files from being deleted unwantedly/unexpectedly.
Comment #22
wim leersThe patch in #20 is wrong, the interdiff is right. This is the correct patch.
Comment #23
effulgentsia commentedAdded a section for the changes to browser requirements.
Comment #24
prestonso commentedFixed a few Markdown issues, converted "Content authoring and site administration improvements" into prose with change records, and added asm89/stack-cors to "Third-party library updates" section.
Comment #25
dawehnerThe current changelog is a bit weird, given it mixes up general features and really specific issues. Is there a specific reason for this verbosity? There are a lot of small bugs listed, which, in case we take it serious, would have to expand even more?
Changes:
Comment #26
xjmThanks everyone!
Thanks @dawehner!
Let's move the comment view up to the site admin improvements section.
For the REST improvements, let's make each item link its issue. Right now it looks like the issues are in a separate list under the text descriptions, so it's just a matter of linking some of the text for the bullet to the relevant issue. (Probably this is just an accident.) If there are any bullets that don't have matching items, we should add them to the first list with their links.
These three items should be under the
aforementionedbug fixes section mentioned below. (They're data integrity issues.) We should describe the benefits of the first issue and link/summarize its change record, then explain that the second two are still open and what the effect of that is.These should be under a section above "New stable modules" for "Important bugfixes since 8.3.x". I'd make it one paragraph something like: "This release includes numerous data integrity bug fixes for revision data, including... These fixes improve revision support for both stable features and the experimental Content Moderation module. ([See below for additional experimental Content Moderation improvements](link).)
Ah I see what's going on here. There are two issues, the initial main patch and the issue to mark it stable. Let's link the original issue in the first sentence instead, and link the second issue where it says "provide a stable core API and data model" in the second paragraph.
On the issue, effulgentsia tagged it because it could be used for performance improvements, so let's move it to the performance section.
Comment #27
xjmI untagged this one, because I don't think it's quite important enough for a release notes mention. The CR should be sufficient. So we can remove it here as well.
Comment #28
xjmOh @dawehner, I agree in general that we should only mention the important issues. If there are any that seem not worth mentioning, could you highlight those? Then we can either untag them, or better explain their significance.
Comment #29
dawehnerAt least for me CHANGELOG.txt seems to be a high level overview, rather a list of change records. Maybe a general paragraph like:
Here is a list of stuff which is a bit meh.
This feels like a minor change, but maybe I'm totally wrong.
These issues seem to be bug fixes, which are of course nice to see fixed, but it feels like to be on the same order of magnitude as probably hundred other bug fixes.
Same comment as above.
Many of those feels like good for change records, but not necessarily for a CHANGELOG.txt. Keep in mind that the bigger the changelog is, the less important media and the other experimental module improvements seems to be.
Comment #30
timmillwoodAdded a bunch of workflows/content moderation issues.
Comment #31
xjmYes, the release notes always include this. Those standard paragraphs are not included in the draft here but will be in the release notes themselves.
Comment #32
xjmFor this one, the usability and accessibility contributors involved were very excited about this change, so that seems reason to include it I guess.
I'll ask the people who tagged the other issues to weigh in on why they proposed them for inclusion. Thanks!
Comment #33
xjmOh on this one:
+* (open) [#2885368: Config export key order for sequences: "orderedby" does not support cases where the order actually matters](https://www.drupal.org/node/2885368)See #26.3; it's included because it's a pending followup related to an important config change. So it's not going to be mentioned on its own.
Comment #34
xjmFor my and others' convenience, here are the remaining issues we're discussing whether to untag:
Edit: Updated with who tagged them and any explanation given.
Comment #35
prestonso commentedWorking actively on a new patch taking into account all the commentary since last patch. Assigning to myself.
Comment #36
prestonso commentedProgress with intervening comments fully (#27, #33) or partially (#25, #26) addressed.
All issues except bugfixes in the "Important bugfixes since 8.3.x" section have initial draft descriptions alongside. Still remaining:
Comment #37
tim.plunkettField Layout
- Only minor bug fixes from 8.3.x to 8.4.x, nothing worth noting
Layout Discovery
- Minor bug fixes
- #2885877: Add support for per-region attributes to Layout Templates, probably not worth calling out
- Marked as stable
Place Block
- Minor bug fix
- #2898267: Mark Place Block as a hidden module marks the module as hidden
Comment #38
GrandmaGlassesRopeManI don't think we should specify a version here. We're already a major version behind and there's an issue to update it, #2878620: Update AirBnB Coding standards to most recent major versions.
Comment #39
prestonso commentedFills out "Important bug fixes since 8.3.x" section with configuration and Content Moderation issues. Addresses #26, #38, and #39.
Currently working with @heddn on the last remaining empty section around Migrate, Migrate Drupal, and Migrate Drupal UI.
Comment #41
dyannenovaAdds some notes for Settings Tray. I'm currently working on looking through the queue and adding more.
Comment #42
andypostComment #43
mpdonadioComment #44
xjmI guess we can remove the words "Note for" here.
This is most sites, so I would put this under "Important bugfixes in this release". I'd also add a paragraph to the effect that the file usage bugs themselves are still outstanding and discussion on how to evolve the file usage tracking system is underway in #2821423: Dealing with unexpected file deletion due to incorrect file usage.
Let's change this to "Updated browser requirements: Internet Explorer 9 and 10 no longer supported".
"...resulting in unpredictable changes in the ordering of configuration and confusing diffs even when nothing had changed."
"To resolve this issue, we've [added an `orderby` key to the config schema] that allows it to be sorted either by key or by value. Adding a preferred sort is strongly recommended.
Comment #45
prestonso commentedThis patch:
Still outstanding; will tackle tomorrow:
Comment #46
xjmHere's the latest from my script
Comment #47
webchickOk, here’s the list of all 8.4.0 release notes issues: https://www.drupal.org/project/issues/search/drupal?text=&assigned=&subm...
Here the ones that are not yet in the latest release notes patch (includes airbnb one caught by script above):
Comment #48
effulgentsia commented#47.1 hasn't been committed yet, so I'm guessing doesn't need a changelog.txt entry yet?
This patch adds for #47.4 and #47.5.
#46, #47.2, and #47.3 are not yet addressed.
Comment #49
xjmWe're iterating on these in real time in a Google doc. We'll resume this issue for 8.4.0 after the alpha ships. Thanks everyone!
Comment #50
xjmAlright, the attached is the result of hours of work by @prestonso, @webchick, and myself. I've proofread all but the following sections:
No interdiff since we changed pretty much every line in one way or another.
Comment #52
xjm/facepalm
Comment #53
xjmComment #54
xjmFor both Workflows and Content Moderation, we should add a section like:
Comment #55
xjmOh and it still needs review for accuracy and clarity, especially the sections I listed in my comment in #50.
Comment #56
xjmOkay, here's the finalish version we're using for the alpha.
If you have additions to make as we go through the beta and RC toward 8.4.0, please make sure the issue is tagged with "8.4.0 release notes" and feel free to add your additions here!
Comment #59
xjmYes, that's because I committed it.
Comment #65
jibranAll the commits which are in 8.4.x and not backported to 8.3.x
git log --oneline --reverse --no-merges --cherry-pick --right-only origin/8.3.x...origin/8.4.x. I think this also helps us finding new issues.Comment #66
cilefen commentedAs we are working on the beta1 release notes right now, the idea has been the beta1 notes should contain just the updates since alpha1. That's ok, and that's what we would usually put on drupal.org. But, what goes in CHANGELOG.txt at beta1? It would be something different than what we would put on drupal.org because CHANGELOG.txt should contain what is building up to be the 8.4.0 notes. In other words: notes about alpha1 + beta1. Any ideas?
Comment #67
xjmThanks @jibran; I spent a bunch of time trying to get a good git command but never found one that worked quite as needed. I'll check that one out.
For the changelog, I don't think we need to commit an update until the minor. Committing the initial draft for the alpha was just an experiment.
However, we could definitely use subject matter experts' help supplying patches on this issue to add to it with additional improvements since alpha1!
Comment #68
gábor hojtsyI started processing issues since alpha1 but indeed, subject matter experts would have a MUCH easier time. I think the ones I did not mark with a @todo I figured out fine but I failed at some things. Also this is just a start of processing the issues since alpha1, not all of them are added yet.
Comment #69
xjmHere's the issues that are tagged but not yet included in #68:
And the release notes for the beta and RC:
https://www.drupal.org/project/drupal/releases/8.4.0-beta1
https://www.drupal.org/project/drupal/releases/8.4.0-rc1
Comment #70
gábor hojtsyI think this reflects the current experimental module statuses well. Did not yet add any new issues to the patch.
Comment #71
gábor hojtsyProcessed the unlisted open issues. In #2860097: Ensure that content translations can be moderated independently @timmillwood argues that is not a regression to list but a task to do. Nothing happened in #2908864: Update CKEditor library to 4.7.3 yet, not sure that is still feasible before 8.4.0? Integrated the only one open issue left. Moving on to the other sections.
Comment #73
gábor hojtsyComment #74
xjmHere, I think we should say "...it is not useful in itself without Content Moderation (still considered experimental for this release) or some other module that extends it."
Minor: trailing space.
It should be hyphenated as "backwards-incompatible", but maybe we could be more direct and say "backwards compatibility breaks from Drupal 8.3.x". And in addition to the upgrade path, maybe we can link them something that shows what the BC breaks are? I imagine it's some list of change records. Also, maybe we should move this paragraph to above the list of specific improvements as it's pretty important information.
Comment #75
gábor hojtsyProcessed the missing critical issues. I contest inclusion of the last three.
Theoretically I added all other criticals from your list @xjm. Your unlitsed fixed issues list also includes unlisted fixed criticals, so after deduping, only these seem to be left from that list:
Integrated this too:
Removing the tag from this one because this is superseded by the also committed #2904142: Update CKEditor library to 4.7.2
Comment #76
nebel54Sorry, flipped the brackets [] and () when linking the issue...
Should be:
A race condition occured in the Batch API when using fastcgi. The Batch API now ensures that [the current batch state is written completely to the database before starting the next batch](https://www.drupal.org/node/2851111).
Comment #77
gábor hojtsyFixed that and two whitespace issues at end of lines.
Comment #78
gábor hojtsyIntegrated #2842298: [policy, no patch] Drop IE9 and IE10 support from Drupal 8.4.x by linking to the issue instead of the change record (as everything else does).
Added #2898344: Add filters to the comments administration pages, #2899156: Update jquery-once to latest release, #2900800: Specify minimum phpspec/prophecy version in core/composer.json and #2833206: Convert Migrate's cckfield plugins to use the new field plugins.
Still missing from the above list:
Comment #80
xjmFail looks like https://www.drupal.org/node/2806697 again.
Comment #81
xjmLatest script output:
Comment #82
xjmMaking some edits.
Comment #83
gábor hojtsyAdded #2850085: Redirects for translation set migration path in Drupal 6 and 7. Tried unassigning so you can do it @xjm, but then needed to step away and the form stopped submitting in the crosspost, sorry.
Comment #84
xjmAttached:
There are still a couple marked with @todo and others missing. We probably also should still remove some of the unneeded items for Migrate and Settings Tray in particular since both are quite long.
Comment #85
xjmAttached rewraps a lot more lines that were miswrapped with links (the closing
]for the text and the opening(for the link need to be on the same line, but other than that they can wrap normally.I also consolidated some more points on Migrate API changes and changed the remaining @todo bits into actual links.
Comment #87
xjmCommitted that since it made the interdiff basically unreadable. That still leaves all these:
Comment #88
xjmAlright, I summarized a bunch of Settings Tray fixes in a single paragraph, and then added in the rest as stubs.
Comment #89
xjmIncorporating the bit about the media_entity contrib module.
Comment #90
cilefen commentedAdded more library update details and some words on the translated cache-clear bug, and the BrowserTestBase/Simpletest dependency.
Comment #91
catchComment #93
xjmBuilding off #91 and moving the revision_translation_affected issue up after the one that spawned it, since it's not in itself specific to Content Moderation.
Comment #96
xjmAll done. Thanks everyone!