I pretty much stopped using/updating the CHANGELOG.txt in all of my projects, after having learned some git fu.

Being able to cleanly cherry-pick + merge commits between branches (including topic/feature branches, so not only the primary major version branches) is way more important than the changelog's purpose.


TwoD’s picture

I don't mind removing CHANGELOG.txt, I only look at git anyway.
How about doing this in a two-step approach? Step one adds a notice at the top of the file saying it will no longer be updated, along with a link to the commit log or release notes. Step two actually removes the file from the repo.

That should prevent users who do not remove the old Wysiwyg folder before extracting a new release from wondering why the changelog is the same.

sun’s picture

Hm, I don't think we need to care for users who are updating modules incorrectly. :) Let's not make this a huge distraction ;)

I'd suggest to simply go ahead and remove it from all current 2.x branches. The removal clarifies that it is no longer maintained. :)

steinmb’s picture

+1 just remove it. We have git log and for people that don't know/use git - just have to use http://drupal.org/node/181465/commits

TwoD’s picture

Shall we push this to all branches or just the main ones for now?

sun’s picture

I actually thought some more about this...

Let me propose the following and you tell me whether that makes sense:

  1. Instead of removing CHANGELOG.txt, we turn it into a document about API changes and additions, and noteworthy changes. Essentially following Drupal core's CHANGELOG.txt.
  2. For example, these recent changes would be noteworthy:

    #1650416: Allow editor specific changes to be made to the profile settings form - Added "settings form callback" to hook_wysiwyg_editor() for editor-specific settings.
    #746524: No Font Styles for CKeditor - Added proper font styles plugin support for CKEditor.
    #614146: Drupal.wysiwyg.editor.instance needs additional methods - Added JS editor instance objects with getContent() and setContent() methods.
    #1679980: Wysiwyg Dialog code is not ported to D7 at all - Ported dialog code to D7.

  3. The changelog does not reference #issue numbers or issue titles. All entries are written manually and independently and in a way that makes sense and makes them human-readable.
  4. All issues that will need a changelog entry are tagged with "API change" and/or "API addition" and/or "API clean-up".
  5. We'll have to go through the existing changelog once in order to rewrite it.
  6. In order to make the maintenance of CHANGELOG.txt not the nightmare it was (requiring "Preparing new release" commits before doing a release), we do not add a version heading for the most recent entries, and only add one for the previous version when adding a new entry after the last release.

    In other words, the CHANGELOG.txt contained in the upcoming 7.x-2.2 release will look like this:

    * Module API
      - Added "settings form callback" to hook_wysiwyg_editor() for editor-specific
      - Ported dialog code to D7.
    * JavaScript API
      - Added JS editor instance objects with getContent() and setContent() methods.
    * Editor support
      - Added proper font styles plugin support for CKEditor.
    Wysiwyg 7.x-2.1
    - Added Foo.
    - Changed Bar.
    - ...

    The heading for "Wysiwyg 7.x-2.2" is only inserted when a new noteworthy change happens in 2.x-dev (for the future 2.3 release).

That said, maintaining a proper changelog is time-consuming and we're generally lacking time and developer resources in the Wysiwyg project. So while I think that this new proposal would make a lot of sense and provide users a very useful overview of actual changes, I also see and realize that less overhead has a good chance of leading to more progress. This needs to be balanced sensibly.

DamienMcKenna’s picture

I recommend improving the Best Practices guide as needed and then sticking to that, adhering to a documentation standard will help everyone.

  • TwoD committed a612176 on 6.x-2.x
    - #1671030: Updated CHANGELOG.txt.
  • TwoD committed 8f12a54 on 7.x-2.x
    - #1671030: Updated CHANGELOG.txt.
TwoD’s picture

Issue summary: View changes
Status: Active » Fixed

We have change records now, let's use that for the major changes and the git history and release notes as usual.

Status: Fixed » Closed (fixed)

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