Changelogs

What’s a changelog?

The changelog is used to keep track of the changes in the plugin introduced in Maintenance Release or Feature releases, they are useful to indicate what things have been changed or added to the plugin. Are usually included inside readme.txt file of the plugins.

Top ↑

Examples

You can take a look at the reference used inside the repository of TEC plugin

== Changelog ==

= [4.6.14.1] 2018-04-18 =

* Fix - Fixed fatal error that would sometimes arise when The Events Calendar was set to display on the front page

= [4.6.14] 2018-04-18 =

* Fix - Updated the "front page" logic to store the value in the DB instead of "mocking" the view via JS [100832]
* Fix - Fixed the generation of PHP warnings on retrieval of posts if the "Include events in main blog loop" option is checked (thanks to Colin Carmichael for reporting this problem) [97667]
* Fix - Made the `tribe-ea-record` custom post type (used to store Event Aggregator record information) private [99106]
* Fix - Expanded the size of the time zone input in the admin to allow for better visibility for long names [100363]
* Fix - If the main events page is set to be the site's front page, ensure it shows as "selected" in the Customizer's front page option [100832]
* Fix - Fixed an issue where failed Event Aggregator scheduled imports would re-attempt the import too soon [102489]
* Fix - Ensure the Tribe Bar displays all the available ranges of dates and times [100646]
* Fix - Hid the filters in the Tribe Bar if a unique view is enabled [75114]
* Fix - Fixed some imported-event handling so that events with no time and that aren't all-day events do not display on the front-end [93979]
* Fix - Changed the HTTP status codes of empty event, venue, organizer, category, and tag archives from 404 to 200 and return empty arrays to stick with WP REST API standard [102283]
* Fix - Better "guessing" on column mapping during the import of CSV file (thanks to April in our Help Desk for flagging this problem!) [96162]
* Tweak - Added the `tribe_aggregator_find_matching_organizer` and `tribe_aggregator_find_matching_venue` filters in Events Aggregator to allow the definition of custom Venue and Organizer match criteria [97292]

Top ↑

Format

Every single changelog has the following format:

* Type - Short description (props if applicable) [TICKET-123]

Every entry usually has the format described above, some are optional in some situations.

Top ↑

Format breakdown

Note: Another important consideration is that the description usually does not have a full stop period.

Top ↑

Process

As of August 2024, The Events Calendar team utilizes the Changelogger tool to manage changelog entries in PRs without creating merge conflicts. This process creates a temporary file with the changelog entry information in the changelog directory, which is merged into the readme.txt and changelog.md files once the release is ready for deployment.

Top ↑

Create Changelog Entries

Once you have a PR set up with your changes following our standards, you can follow these steps to add the changelog entry to your PR:

1. Pull the most recent version of the master branch for the repository of the plugin you are making changes on (i.e. git checkout master && git pull)- this will ensure that you have the necessary Changelogger script files.
2. Run composer install – since the Changelogger tool is a dev dependency, this will ensure you have all the necessary dev files.
3. To start the changelog entry script execute npm run changelog – this will prompt you through the following questions:
   • ‘Name your changelog file’ – Defaults to the current branch. This file is intended to be temporary, so the name of the file is mostly used to help keep the various changelog files organized. Make sure to not have any spaces in the filename as this will cause issues for Windows users.
   • ‘Significance of the change’ – Options are:
     • [p@tch] Backwards-compatible bug fixes.
     • [minor] Added (or deprecated) functionality in a backwards-compatible manner.
     • [major] Broke backwards compatibility in some way.
   • ‘Type of change’ – See below
   • ‘Changelog entry’ – May not be empty, unless the significance is patch. From the section above, include a short description, props if applicable, and the Jira ticket if applicable. This should follow the format of Short description (props if applicable) [TICKET-123]
4. You should see the file added to the changelog directory (there might be a slight delay until it shows). Add and commit this file to your PR and push the new file along with the changes in the PR.

Top ↑

Merge for Release

1. On the release branch, check that all intended changelog entries are in the changelog directory.
2. Execute the command ./bin/process-changelog.sh, which accepts 4 arguments.
   • RELEASE_VERSION – The upcoming version. Follow standard formatting guides.
   • CURRENT_VERSION – The current version – even though this is required it is only useful when the ACTION_TYPE is either amend or amend-version
   • ACTION_TYPE – Default is generate, with other options are amend and amend-version
     • generate: The default, will remove all existing changelog entries from the changelog directory and CREATE new changelog entries in changelog.md and readme.txt files.
     • amend: Run when the changelog entries for the RELEASE_VERSION are already generated and will find NEW changelog entries in the changelog directory and append those to the already existing changelog entries both in changelog.md and readme.txt
     • amend-version: Run when the changelog entries for the RELEASE_VERSION are already generated and will ONLY amend the header. This is useful when you simply want to change the version or/and the date of the release.
   • RELEASE_DATE – Defaults to today. Accepts the date of the release in a human readable format.
     • NOTE: This argument uses UTC+0 timezone. This means if you are running the command in NY timezone at 11pm on the 22nd of June, the date in UTC is already the 23rd of June, which is what will show on your entry.
   • EXAMPLE: ./bin/process-changelog.sh x.y.z x.y.k generate tomorrow
3. You should see the files deleted from the changelog directory and new entries added to the changelog.md and readme.txt files.

Top ↑

Order of entries

The following is the list of changelog entry prefixes that we use within our readme.txt files. The order is where the priority of each should be when placing them within a changelog. (NOTE: The Changelogger tool currently orders the entries alphabetically by prefix, but this is planned to be updated to this order in the future).

1. Version
2. Feature
3. Fix
4. Tweak
5. Performance
6. Security
7. Accessibility (Use it sparingly for major changes/initiatives. Otherwise Tweak is better)
8. Compatibility (Use it sparingly for major changes/initiatives. Otherwise Tweak is better)
9. Deprecated
10. Language