Emil Uzelac 5:38 am on January 7, 2013
Tags: Theme Documentation ( 6 )

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 tracTrac Trac is the place where contributors create issues for bugs or feature requests much like GitHub.https://core.trac.wordpress.org/., 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!

#theme-documentation

Kathy Jensen 1:03 pm on January 7, 2013

I think it should be required.
John Gardner 1:09 pm on January 7, 2013

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
  
  I would happy to do that with my themes.
toscho 1:45 pm on January 7, 2013

SVNSVN Apache Subversion (often abbreviated SVN, after its command name svn) is a software versioning and revision control system. Software developers use Subversion to maintain current and historical versions of files such as source code, web pages, and documentation. Its goal is to be a mostly compatible successor to the widely used Concurrent Versions System (CVS). WordPress core and the wordpress.org released code are all centrally managed through SVN. https://subversion.apache.org/. 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.
- Anonymous User 1:58 pm on January 7, 2013
  
  this is a good point @toscho.
- Amy Hendrix (sabreuse) 2:15 pm on January 7, 2013
  
  For me, the fact that SVNSVN Apache Subversion (often abbreviated SVN, after its command name svn) is a software versioning and revision control system. Software developers use Subversion to maintain current and historical versions of files such as source code, web pages, and documentation. Its goal is to be a mostly compatible successor to the widely used Concurrent Versions System (CVS). WordPress core and the wordpress.org released code are all centrally managed through SVN. https://subversion.apache.org/. (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
    
    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
      
      In all honestly, SVNSVN Apache Subversion (often abbreviated SVN, after its command name svn) is a software versioning and revision control system. Software developers use Subversion to maintain current and historical versions of files such as source code, web pages, and documentation. Its goal is to be a mostly compatible successor to the widely used Concurrent Versions System (CVS). WordPress core and the wordpress.org released code are all centrally managed through SVN. https://subversion.apache.org/. 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 GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/ for proper VCS for Theme development. (Or, roll your own SVN/GitGit Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency. Git is easy to learn and has a tiny footprint with lightning fast performance. Most modern plugin and theme development is being done with this version control system. https://git-scm.com/. 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
Pingback: Should Theme Changelogs Be Required or Recommended? - WP Daily
Evan Mullins 2:09 pm on January 7, 2013

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

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

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
  
  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
  
  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.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://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
    
    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 HTMLHTML HTML is an acronym for Hyper Text Markup Language. It is a markup language that is used in the development of web pages and websites.-formatted change log that renders in the contextual help tab for the Theme. I do have a PluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party 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

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

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

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 BBPressbbPress Free, open source software built on top of WordPress for easily creating forums on sites. https://bbpress.org. plus Plugins with function to pull data from separately hosted svn ? We basically can change ‘some data’ through that svn commit with our pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party 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 GitGit Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency. Git is easy to learn and has a tiny footprint with lightning fast performance. Most modern plugin and theme development is being done with this version control system. https://git-scm.com/. : 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. GithubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/’s self hosted software costs a bomb and not under GPLGPL GPL is an acronym for GNU Public License. It is the standard license WordPress uses for Open Source licensing https://wordpress.org/about/license/. The GPL is a ‘copyleft’ license https://www.gnu.org/licenses/copyleft.en.html. This means that derivative work can only be distributed under the same license terms. This is in distinction to permissive free software licenses, of which the BSD license and the MIT License are widely used examples. 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

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
  
  most definitely, but maybe not all, link to svn might be good 🙂