Problem/Motivation

Webform is not a simple module. It depends an a number of libraries and its feature set is growing fast. Stated succinctly it changes a lot. A number of times now when I have performed updates I have had to search google and the issue queue to figure out what was going on. Here are a few examples that could have been included in a UPDATE.md for the first release they were inculded in:

  • Contribute module was made a dependency of Webform. Deployment to live site failed as the module was not installed nor enabled on development site by upgrade.
  • jQuery support changed from 2.x to 3.x
  • Image Select was moved to its own module
  • iCheck is no longer be supported by Webform(future - currently message in the UI warning about this.)

Proposed resolution

Consider adding an UPDATE.md to the project that can be used to allow those performing system updates to get the concise information needed to perform updates without needing to search for it. For an example of the format that this file can take see the UPDATE.md from the Lightning project.

Not sure if it is possible to add an UPDATE.md to the older versions of webform for those that have not yet upgraded, but it might be useful to those who have not yet upgraded from older versions. If so then I would suggest starting back as far as you you want to add it then work forward adding the changes for each release.

Comments

frederickjh created an issue. See original summary.

frederickjh’s picture

Issue summary: View changes
frederickjh’s picture

Issue summary: View changes
frederickjh’s picture

If this was to be added to past releases the changelog would be a good place to find items to be added to the UPDATE.md.

frederickjh’s picture

StatusFileSize
new874 bytes

Patch to add UPDATE.md. I started the section for the update notes for the next release at the end. Normally the newest release will be at the top of this section.

frederickjh’s picture

StatusFileSize
new2.04 KB

New patch with instructions added to the RELEASE-NOTES.md.

jrockowitz’s picture

I completely agree that people need to know what has changed between releases.

As of RC1 we have been maintaining change records.

For now, we should mirror exactly what Drupal core is doing, which is linking to the change records.

@see https://cgit.drupalcode.org/drupal/tree/core/CHANGELOG.txt

By linking to these change records, instead of embedding them, we are encouraging users to use D.O and hopefully, more module maintainers will start writing change records.

jrockowitz’s picture

Here is what I think should go into CHANGELOG.md

New releases of the Webform module for Drupal 8 with bugs fixes 
and new features are released every month.

* For a full list of fixes in the latest release, visit:  
  https://www.drupal.org/project/webform/releases?api_version%5B%5D=7234

* Read the Webform's API and feature change records which describe changes 
  and its impact on site users, site builders, themers, and module developers
  https://www.drupal.org/list-changes/webform/published?to_branch=8.x-5.x

jrockowitz’s picture

Status: Active » Fixed

I committed the text from #8. Feel free to post any suggestions that can be added to this text.

frederickjh’s picture

If that is the way you want it.

I think change logs are good but not for this purpose. Many times it is like an easter egg hunt. I think that this approach is taking the easy way out.

Installing and maintaining Drupal 8 has been pushed to a whole new level compared to Drupal 7. I think that approaches like these do not help bring more clarity to the situation, however I am not a maintainer of the module and I realize that it would involve an ongoing commitment of resources by the maintainers. So, I find this approach is better than no UPDATE.md at all.

jrockowitz’s picture

I realize that it would involve an ongoing commitment of resources by the maintainers

There are only 2 maintainers and the ongoing commitment would fall on my shoulders.

This approach is easier, at the same time it pushes everyone to start paying attention to the Webform module's changelogs on Drupal.org.

In theory, someone could write a drush command that generates/updates the CHANGELOG.md using Drupal.org's APIs

https://www.drupal.org/api-d7/node.json?type=changenotice&field_project=...

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.