Changelog: Recommendation or Requirement?
Theme Documentation:
In lieu of a readme.txt file, Themes are recommended to include a changelog, indicating version-to-version Theme changes.
In past months we noticed that Theme Authors either do not have the changelog or the changelog is very poor.
Here are some examples:
Changelog
- Version 1.1 – Improvements
- Version 1.1 – Minor Menu Changes
- Version 1.1 – Font Size Change
Which does not really say anything at all.
Or the changelog that was not updated in months.
Luckily for us we have trac, but it would be easier for us and for users to know what is going on when author releases a Theme.
Please share your thoughts.
Thanks!
Danielx64, 
Kathy Jensen 1:03 pm on January 7, 2013 Permalink |
I think it should be required.
John Gardner 1:09 pm on January 7, 2013 Permalink |
Personally I’d like to see this as a requirement, but only if the changelog is visible from the WordPress update screen (like they it is for plugins), which I don’t believe is currently the case. Short of that, I’d leave it as a recommendation.
Schwarttzy 5:02 pm on January 7, 2013 Permalink |
I would happy to do that with my themes.
toscho 1:45 pm on January 7, 2013 Permalink |
SVN discourages atomic commits (slooow), so most authors will commit a bunch of changes in one rush … and forget the details. I don’t say it would be better with a faster version control, but there were fewer excuses.
So, as long as SVN is the default don’t make it a requirement.
John Saddington 1:58 pm on January 7, 2013 Permalink |
this is a good point @toscho.
Amy Hendrix (sabreuse) 2:15 pm on January 7, 2013 Permalink |
For me, the fact that SVN (and our review system) encourages bundling a bunch of changes instead of atomic commits is *more* reason to require a changelog, not less. I can’t tell you how many theme updates I’ve seen that include a handful of bug fixes and several new features under “updates”, if they document it at all.
toscho 2:37 pm on January 7, 2013 Permalink |
I see the need for good changelogs.
My point is: the current system makes it hard to write that automatically. You cannot say to people who are mostly not programmers: Hey, here is a task we made extra difficult, so it is a requirement.
Chip Bennett 3:08 pm on January 7, 2013 Permalink |
In all honestly, SVN is used only as a *repository* for Themes; it clearly isn’t set up to be a proper version control system for WPORG-hosted Themes. (Commits are irrelevant, since Theme developers can’t SVN-commit directly – and given the way the Extend directory is set up, probably will never be able to do so.)
I strongly recommend using something like GitHub for proper VCS for Theme development. (Or, roll your own SVN/Git locally.)
All that said: I don’t think that themes.svn should be a determining factor here; we’re only using SVN serve tagged versions of Themes
Should Theme Changelogs Be Required or Recommended? - WP Daily 2:07 pm on January 7, 2013 Permalink |
[...] when it was asked on the Make boards whether or not changelogs should be required or recommended I felt a twinge of shame as I know [...]
Evan Mullins 2:09 pm on January 7, 2013 Permalink |
I agree with John, This should be required and displayed as it is for plugins on the update screen. Users should really be empowered to know what is included in an update. This would be especially helpful if they done specific work in any area that has been updated or at least alert them as to where to look the closest to make sure nothing is broken post-update.
Edward Caissie 2:26 pm on January 7, 2013 Permalink |
I would be more than happy to support a “RECOMMENDED” status for a changelog file, but I would not be willing to make it a “REQUIRED” theme element any time soon.
What I would recommend is theme authors, once they have successfully submitted a ticket for the latest version of their theme, is write (copy and paste works, too) a changelog as the first comment for the ticket. I see this as a more valuable addition than simply including a changelog file on its own.
Chip Bennett 2:57 pm on January 7, 2013 Permalink |
Well, that provides a useful change log for the Theme *reviewer*, but doesn’t help the Theme *end user*. I think both use-cases are valid with respect to the benefits of having a change log.
Chip Bennett 3:00 pm on January 7, 2013 Permalink |
From the perspective of ever-improving standards toward best practices, I support moving toward eventually making change logs *required*.
I think the first step is clarifying that a change log, whether as a stand-alone file or as part of readme.txt, is *recommended*.
Also, I think that we should clarify to Theme developers that including a detailed change log is a great way to expedite Theme reviews, because it is a tremendous aid to the reviewer in following/understanding the changes in any given Theme revision.
Jack Tarantino 4:08 pm on January 7, 2013 Permalink |
I agree completely. I think after strongly recommending a changelog, it might be best to have WordPress display changelogs for themes so it becomes a more useful feature. Then later start requiring them.
Schwarttzy 5:21 pm on January 7, 2013 Permalink |
I think stand alone file would be better, no reason to have a file changing all the time when we could just have a specific file for it. Also we could define out some sort of formatting so that data can easily be harvested from the file.
I would love to have some integration with the WordPress.org page for themes which would give me a bigger reason to document and be more detailed with updates to the theme. Also while we are at it, why not add some information of the updates on the WordPress theme pages (where you pick and choose from the different themes on a WordPress Install)? Reason behind that is because I have people using my themes that have never even browsed to WordPress.org, surprisingly they stay on their website the entire time.
Chip Bennett 5:49 pm on January 7, 2013 Permalink |
For standardization, and hopefully to facilitate integrating into the Themes’ Extend listing page, I strongly recommend using the Plugin Readme Standard.
If you split the change log into a separate file, I would recommend retaining the Readme Standard markup conventions for the change log itself.
(Note: I don’t follow this recommendation in my own Theme, because I have an HTML-formatted change log that renders in the contextual help tab for the Theme. I do have a Plugin Readme Standard-conforming readme.txt, but its change log is an overview of the more-detailed changes in the HTML file.)
Justin Tadlock 8:18 pm on January 7, 2013 Permalink |
Until themes are treated like plugins with a readme.txt file or a similar system, I’d only go with “recommended”. Outside of that, changelogs are practically useless for a large portion of users. Only those users who are “advanced” enough to look into the theme files will ever see it.
Emil Uzelac 4:21 am on January 8, 2013 Permalink |
Is it safe to say that we can add a recommendation after the Theme was submitted? (Theme Check part).
That might encourage authors, or at least remind them about it.
And also what’s preventing Themes to be treated like Plugins? I am asking because I don’t really know what’s behind
That would be very helpful when Theme updates are available. Right now the link WordPress includes is leading to the listing in directory and that’s a dead end for users because we can’t include anything but description.
Thanks everyone,
Emil
Jose Castaneda 11:07 pm on January 9, 2013 Permalink |
I say we make it a recommendation but making it a strong recommendation. Have the reviewer state that for next submission strongly advice a changelog to facilitate the review process.
Abhishek Ghosh 11:56 am on January 9, 2013 Permalink |
I would agree with @Emil Uzelac at most points specially with the point “themes to be treated like Plugins”.
Is not the formula of ‘what’s behind’ for WP plugins landing page is BBPress plus Plugins with function to pull data from separately hosted svn ? We basically can change ‘some data’ through that svn commit with our plugin repo. A plugin developer actually never get access to Plugins webpage directly (that is normal). The probable difference among the Themes and Plugins is the mother template. Themes has some extra and less things compared to that plugin page.
WPORG Git : Actually a WPORG hosted git would solve the versioning and detailed wiki issue. Usually people knows about git more than svn on average. The problem is not simple to solve. Github’s self hosted software costs a bomb and not under GPL 2.0 or later. Free Git softwares are actually not of same quality like GitHub Enterprise. Known free options are Gitorious and Gitolite.
So possibly changing that Themes template might work. May be a trial can be run to test.
Danielx64 4:15 am on January 24, 2013 Permalink |
Something to add, what would happen if a theme is completly rewritten and only say 20% if left from the last version? How would you put that in the change log?
Emil Uzelac 7:49 pm on January 24, 2013 Permalink |
most definitely, but maybe not all, link to svn might be good