Ask Slashdot: To Publish Change Logs Or Not?

Linnerd writes "A software company I work for has decided to no longer publish change logs when updated versions of the software are made available. A change log consists of sections pulled directly from the issue management system that is automatically processed into a spreadsheet. The spreadsheet can be sorted/viewed by many criteria, such as date of the fix, component affected, severity and more. There usually are a fair number of entries (sometimes more than 1000), because each update published contains all the accumulated changes made since some base release in the past and the change log has entries for everything from major bugs to minor improvements to documentation changes and spelling errors fixed. The main reasons for pulling the change logs was the fear of putting the software in a bad light and risking ridicule, especially from the competition. Although I can follow these arguments up to a point, I've personally always been more comfortable with software that had explicit and detailed change logs: Errors and bugs happen, whether they are communicated or not, and I'd rather know what was changed than blindly install some patch without knowing if it's relevant for the issues I'm trying to solve. What is your opinion? Should change logs / errors / bugs be communicated openly? How is this handled in the companies you work for? Can you provide publicly available references on the pros and cons of open and honest communication of changes and bug fixes, especially in commercial environments?"

Comments

Change logs matter

[Marsell]

Anybody who has run software on a non-trivial scale knows how important changelogs are.

They give you some idea of what to expect, but more importantly let you know whether a problem you're having now has been fixed in the upgrade. Although developers would like everyone to run the newest version of software, in practice you don't touch production systems without good reason. Fixed pain points, and maybe security (depending on isolation) are valid reasons. "Because it's there" is not.

Elimination is a stupid move. It's a triumph of marketing at the cost of we who must run this shit.

Re:Change logs matter

[s.petry]

This is why there are generally 2 sets of change logs (in reality one that derives another set). You have the changelog that is used internally, which is what you are talking about. The other is a list of bug fixes, enhancements, and removed features for customers.

Good internal change logs track not only what was fixed, but what was attempted in the fix process so that you don't replicate these failed paths in later problems/enhancements. Code samples are usually in "good" change logs as well. These things are not needed for a customer, and are probably where you would find the ridicule.

If you are really being told to remove change logs, that is a very broken situation. Those logs are not just to show people you are actively developing your code and fixing things, but also to reduce your overall development costs.

Definitely

[kimvette]

Change logs and proper release notes are very appreciated by administrators and end users. Disclosure of known issues is particularly valued, and it also benefits the vendor because it reduces nuisance calls to technical support. Fixed, pending and wontfix lists are especially appreciated by sysadmins, since they are the ones most immediately impacted by the change - do they install the patch and deploy it immediately, or do they live with the current build until pending issues are fixed, etc.

Plus, it instills trust. A veil of secrecy does not earn trust from your customers, nor does a vague "fixed misc. bugs and implemented misc. performance enhancements" because one is more inclined to not upgrade rather than proceed with it and possibly risk downtime.

Of course I am saying this blindly, since the submitter did not specify what sort of software this is. Is it a server app? A commercial desktop app? Or is it a game or other entertainment software which is not mission-critical, where downtime can cost thousands to tends of thousands per hour?

Yes, POST change logs

[mysidia]

It is one of the major criteria I look for in good software --- open communication from the developers about updates, and changes; active recent update history.

Some of the most successful software companies such as Microsoft and VMware post detailed released notes that show bug fixes and improvements.

Detailed changelogs are even better.

If you are concerned about ridicule from a competitor -- you can probably point out the competitor hides their flaws by not posting detailed change logs.

Another thing you can do that's less recommended -- is put the changelogs behind a click-through agreement. Require site visitors register to review them.

Keep in mind it's not just customers that necessarily want to see documentation, release notes, and changelogs.

When I am considering buying a software product I want, EXPECT, and demand to see on the product vendor's website: (1) Pricing, (2) Release notes, (3) Documentation, (4) Change logs, and (5) A trial version download, before I even talk to a salesperson.

These are signs of a healthy well-marketed product, that will be around for years to come. If any of these are missing -- warning flags, or alarm bells are going off.

If the software doesn't have readily accessible documentation, or notes on bugs --- does anyone use this software in the real world?? Is the documentation crap??; If I buy this product -- is it going to be a complex pile - have spending hours upon hours on the phone with their support, working out bugs at every corner just to get the product up and running with basic functionality?

Will I need to make a phone call, to blow my nose with this software?

Not exactly cloud, but kinda

[rve]

We make a SaaS application. Every major release comes with a change log. Not the raw, unedited and complete change log TFA talks about, but a human readable, edited one of the form
- feature we promised
- change you asked for
- other change you asked for
- new surprise feature
- UI improvement foo

and finally....
- numerous bug fixes

Bugfix releases don't have a separate published change log. Instead, customers who reported a bug are notified directly when it has been fixed.

This way it is useful for the customer. What the customer really wants to know is that they're not paying you for drinking coffee. They don't want information overload. A complete change log would only make sense to people who work with the code.