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.
| Comment | File | Size | Author |
|---|---|---|---|
| #6 | webform-add-update.md-2955115-6.patch | 2.04 KB | frederickjh |
| #5 | webform-add-update.md-2955115-5.patch | 874 bytes | frederickjh |
Comments
Comment #2
frederickjhComment #3
frederickjhComment #4
frederickjhIf 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.
Comment #5
frederickjhPatch 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.
Comment #6
frederickjhNew patch with instructions added to the RELEASE-NOTES.md.
Comment #7
jrockowitz commentedI 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.
Comment #8
jrockowitz commentedHere is what I think should go into CHANGELOG.md
Comment #10
jrockowitz commentedI committed the text from #8. Feel free to post any suggestions that can be added to this text.
Comment #11
frederickjhIf 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.
Comment #12
jrockowitz commentedThere 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=...