?
avatar acs-ferreira
acs-ferreira
8 Dec 2016

It would be helpful if a changelog was added on the releases page after each release.
My 2 cents.

avatar acs-ferreira acs-ferreira - open - 8 Dec 2016
avatar joomla-cms-bot joomla-cms-bot - change - 8 Dec 2016
Labels Added: ?
avatar joomla-cms-bot joomla-cms-bot - labeled - 8 Dec 2016
avatar Bakual
Bakual - comment - 8 Dec 2016

You can filter the GitHub PRs by milestone. That gives you that list (eg https://github.com/joomla/joomla-cms/milestone/16?closed=1). There is no other changelog.

Do you think it would be helpful to add that link to the release page (eg to https://github.com/joomla/joomla-cms/releases/tag/3.6.3)?

Imho, that list is so big, it isn't helpful to anyone anyway.

avatar mbabker
mbabker - comment - 8 Dec 2016

What would the difference between a changelog and https://github.com/joomla/joomla-cms/milestone/16?closed=1 or 3.6.2...3.6.3 be?

(Just trying to figure out what it is you're looking for here)

avatar jeckodevelopment
jeckodevelopment - comment - 8 Dec 2016

3.6.2...3.6.3 doesn't show all the commits

avatar acs-ferreira
acs-ferreira - comment - 8 Dec 2016

When we maintain a lot of software, changelogs are just important.
http://keepachangelog.com/en/0.3.0/

It is very complicated to jump over milestones to understand what has changed since last release.

avatar jeckodevelopment
jeckodevelopment - comment - 8 Dec 2016

agree @acs-ferreira , but it's not so easy to keep up to date a changelog when you have a lot of PRs merged each release, that's why GitHub provides this feature and this link should work:
https://github.com/joomla/joomla-cms/milestone/16?closed=1

avatar mbabker
mbabker - comment - 8 Dec 2016

3.6.2...3.6.3 doesn't show all the commits

Because GitHub limits the UI view. Using a git client you can do a full diff.

When we maintain a lot of software, changelogs are just important.

Agreed. The milestone links provided above serve as that. This link is also standard in the release announcements unless it's a "special" release in which case individual items are listed in the announcement instead.

What are you looking for that isn't already provided by that data? That is what I'm trying to understand now.

avatar acs-ferreira
acs-ferreira - comment - 8 Dec 2016

@jeckodevelopment agree too, but you must agree that consulting something like this is more user friendly than milestones https://github.com/PrestaShop/PrestaShop/releases/tag/1.7.0.1

But having a link like https://github.com/joomla/joomla-cms/milestone/16?closed=1 on the releases page is a very good first step IMO.

avatar mbabker
mbabker - comment - 8 Dec 2016

FWIW we used to maintain a text CHANGELOG file. It was in essence the same thing you could get from the GitHub milestone view but was something that had to be manually updated by whomever was merging pull requests. There's really no point in manually maintaining a file that is basically the same thing as the commit log which is why we stopped.

Yes, those "formatted" change lists are nice for human consumption, but unless someone is going to maintain that list during the entire release cycle (if you look at our releases it's easy to get over 250 changes in one release) it's going to add a massive burden to the release team to try and sort through the milestone item list to categorize everything. The next argument is "well, you can just list important items". That's honestly a subjective list and what's important to me might not mean a thing to others.

I want to do something in the issue tracker to help with this (see joomla/jissues#506). It'd be "easier" to work from there because the tracker has extended categorization, we aren't pushing that into GitHub in any way. But, I'm only one person and after four years it's still difficult to find folks who will help with the issue tracker's code.

avatar Bakual
Bakual - comment - 8 Dec 2016

That link is already in the release announcement (see https://www.joomla.org/announcements/release-news/5676-joomla-3-6-3-released.html). It is just not on the GitHub release page (eg https://github.com/joomla/joomla-cms/releases/tag/3.6.3).

Something like what PrestaShop does just doesn't work when you have over 300 merged PRs.

avatar acs-ferreira
acs-ferreira - comment - 8 Dec 2016

@mbabker i follow a lot of Git projects by it's ATOM, so on my client i can have a quick overview of changes.

Check https://github.com/joomla/joomla-cms/releases.atom and https://github.com/PrestaShop/PrestaShop/releases.atom and you'll understand.

avatar acs-ferreira
acs-ferreira - comment - 8 Dec 2016

@Bakual Prestashop is just an example, maybe not the best one as they release more frequently than Joomla so releases are smaller, i agree.

avatar mbabker
mbabker - comment - 8 Dec 2016

The GitHub releases view was never meant to be an "official" release listing, we just needed some place to push our packages once JoomlaCode crapped out trying to support our traffic.

avatar acs-ferreira
acs-ferreira - comment - 8 Dec 2016

I understand that point of view, but software is writed for people mainly, not for machines. People must understand what has changed, and by "people" i mean that big % of Joomla users that doesn't know what 'diff' means, what 'PRs' means, etc.

It is a good thing to have code best practices, maintaining a human-readable changelog should be a best practice too.

As http://keepachangelog.com/en/0.3.0/ writes:

Why should I care? Because software tools are for people. If you don’t care, why are you contributing to open source?

If i can contribute in some way...

avatar acs-ferreira
acs-ferreira - comment - 8 Dec 2016

Take a look at Wordpress, they also don't push a changelog with each release on their Git, but:

https://codex.wordpress.org/Version_4.6.1

You must agree that you can track & follow that software in a perfect way!

avatar jeckodevelopment
jeckodevelopment - comment - 8 Dec 2016

It would be nice to have the "List of Files Revised", but here that list could become a book.

avatar mbabker
mbabker - comment - 8 Dec 2016

The milestone list IS human friendly though. It just lacks things like categorization.

If someone wants to maintain one I'm not going to stop them, but I don't see value in a changelog file in the format we used to maintain (which was in essence the commit log with a couple of arbitrary symbols and separated by date) and unless someone is actively maintaining this resource during a release period it's going to be too big of a burden to request the release team try to parse a 400 item milestone list to come up with an arbitrary list of "important" changes at the end of the cycle (which is what I see a lot of larger software platforms listing as their changelog).

avatar jeckodevelopment
jeckodevelopment - comment - 8 Dec 2016

The milestone list IS human friendly though. It just lacks things like categorization.

Yes, it's easy to read and it gives also the opportunity to know more about each change.
It can have categorization thanks to labels. Maybe we can improve labels?

avatar acs-ferreira
acs-ferreira - comment - 8 Dec 2016

IMO, each PR should be = to a line on the changelog. The person validating the PR should only write a simple line on the CHANGELOG.md. I don't think this is a "mess" if it is a standard.

This should follow a workflow, not be a "one-time job" just before releasing.

avatar mbabker
mbabker - comment - 8 Dec 2016

We were purposefully trying to NOT send all of the status and category data from the issue tracker to GitHub in the form of the labels. In all honesty though, if you want to bring that data in, I'm going to ask the question of "what value does the issue tracker then have when the data we wanted a separate issue tracker for is now stored into GitHub?". Because let's just be honest here, the issue tracker's maintenance falls on two or three people at best.

IMO, each PR should be = to a line on the changelog.

Then the changelog becomes an equivalent to the commit log or issue listing in each release milestone. What value is that adding?

avatar jeckodevelopment
jeckodevelopment - comment - 8 Dec 2016

Then the changelog becomes an equivalent to the commit log or issue listing in each release milestone. What value is that adding?

same opinion of @mbabker

avatar acs-ferreira
acs-ferreira - comment - 8 Dec 2016

Can you identify the commits belonging to the SECURITY, CORE, BACK OFFICE and FRONT OFFICE, FEATURES ADDED/REMOVED on the milestones releases? If yes, good. If not...

avatar jeckodevelopment
jeckodevelopment - comment - 8 Dec 2016

@acs-ferreira if you read the release announcement:


What's in 3.6.4

Version 3.6.4 is released to address two critical security issues and a bug regarding two-factor authentication.
Security Issues Fixed

High Priority - Core - Account Creation (affecting Joomla! 3.4.4 through 3.6.3) More information »
High Priority - Core - Elevated Privileges (affecting Joomla! 3.4.4 through 3.6.3) More information »
High Priority - Core - Account Modifications (affecting Joomla! 3.4.4 through 3.6.3) More information »

Bug Fixes

[#12497] Two-Factor Authentication encryption fix

Please see the documentation wiki for FAQ’s regarding the 3.6.4 release.
https://www.joomla.org/announcements/release-news/5678-joomla-3-6-4-released.html

avatar mbabker
mbabker - comment - 8 Dec 2016

We don't separate items by "core", "back office", or "front office" though. The categorization used on the issue tracker breaks down to things like "templates", "libraries", and "components"; there really isn't a distinction between a backend fix and a frontend fix.

Also, you'll never see the security issues in that listing. Private resources are used for all of the security tracking and the fixes are never merged individually with distinctive commit titles. That's what the security announcements are for (also referenced in each release announcement).

avatar mbabker
mbabker - comment - 8 Dec 2016

And again, if we're going to suggest the issue tracker's categorization belongs as GitHub labels, I'm going to suggest we don't need the issue tracker. We don't have adequate resources to be maintaining and improving it in the ways we want it to grow and considering its primary purpose is to track issue data, if none of that data exists on the tracker then why bother with it?

avatar Bakual
Bakual - comment - 8 Dec 2016

You're asking to categories each PR. Most of them probably would fall into multiple categories
As said already we just don't have the resources to do that.
Maintaining a changelog would add a lot of work.
With GitHub, merging is a simple click with the mouse. Plus two to assign the milestone.
If you need to edit the changelog and categorise the PR and write a summary.... Welll.... That reduces the code we can merge in the same time massively..

Keep in mind nobody is paid here. Unlike other projects.

avatar acs-ferreira
acs-ferreira - comment - 8 Dec 2016

Keep in mind nobody is paid here. Unlike other projects.

Open Source Mathers :)

https://github.com/skywinder/Github-Changelog-Generator

avatar Bakual
Bakual - comment - 8 Dec 2016

Probably works for small projects like the one there. I still don't see how a list of 350 PRs would be useful to anyone. Even if categorised. ANd now think about it again and take into account that a PR may have multiple categories.
To have a useful changelog, it would need manual processing. Otherwise it doesn't add anything to the existing changelogs provided by GitHub. And for manual processing there is no ressources.

avatar acs-ferreira
acs-ferreira - comment - 8 Dec 2016

Ok, if you think it is not sustainable/doesn't add any value to the project, feel free to close this topic.

avatar Bakual Bakual - close - 8 Dec 2016
avatar Bakual Bakual - close - 8 Dec 2016
avatar Bakual Bakual - change - 8 Dec 2016
Status New Closed
Closed_Date 0000-00-00 00:00:00 2016-12-08 16:19:15
Closed_By Bakual
avatar mbabker
mbabker - comment - 8 Dec 2016

If I could ever find time/resources to build out joomla/jissues#506 then we could have something that's user friendly and usable (i.e. we could implement a way to filter items on category). But for the processes we have now, the only feasible "manual" changelog would equate to what we used to do with listing each commit in a file, so the best we can offer is a link to GitHub's milestone view and let users work with that.

avatar acs-ferreira
acs-ferreira - comment - 8 Dec 2016

the best we can offer is a link to GitHub's milestone view and let users work with that

Better than nothing ?

Add a Comment

Login with GitHub to post a comment