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

Your customers are lucky

[phantomfive]

Your customers are lucky, they get to know that something changed. If you were making 'cloud' software, they wouldn't know anything changed until they logged in one morning and things are broken.

Re:Your customers are lucky

[Anonymous Coward]

I guess playing devil's webmaster, would there be any possible NEGATIVE consequence of publishing the change log? I don't see it for most applications.

Liability.
Client X has some kind of trouble, looks through the changelog and finds bug Z was fixed and (at least on the surface) appears to have been related.
Most of the time when you're dealing with proprietary solutions (not just software), you don't give the client a full detail of what happened when something went wrong. You go through management to prepare a formal RFO (reason for outage), that way they can clear it with the Legal team, Sales teams, and verify the accuracy of the statement.

Re:Your customers are lucky

[istartedi]

Your customers are lucky, they get to know that something changed. If you were making 'cloud' software, they wouldn't know anything changed until they logged in one morning and things are broken.

Worse yet, they could get a screen full of MyCleanPC spams mixed in with their data.

Re:Your customers are lucky

[Cenan]

I see your point. But liability and truth are not the same thing, and losing in court has nothing to do with truth either.

Re:Your customers are lucky

[Anonymous Coward]

I block MyCleanPC spam with a hosts file. Thank you for being a cosmonaut.

Re:Your customers are lucky

[necro81]

But liability and truth are not the same thing

This is a practice that has been drilled into my head: any half-thoughts, offhand comments, or speculation can very, very easily be manipulated by a lawyer to make you or your company look like a guilty guilty liars in a courtroom. One excerpt from a change log, blown up onto a 4' x 6' poster, displayed in front of a jury, can result in a multimillion-dollar loss for you or your company. Never mind that the full context would exonerate you or that there's a larger story surrounding that comment - the opposing lawyer only needs to keep pointing to that poster to make you look like an idiot that's got something to hide.

Now, it is bad enough for such potentially dangerous content to exist in materials that are discoverable once a lawsuit has already begun. It is downright stupid, as a business practice, to just put those materials out in the wild for anyone to examine and look for something that could be sued over. If you want to keep your customer informed about what's changed, by all means produce a formal document that does that, with detail to the nth degree. The change logs are for internal use; they aren't for your customers.

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.

Re:Change logs matter

[bored]

Code samples are usually in "good" change logs as well.

Code samples for what? The library your selling? I don't think i've ever put a "code sample" in a changelog for human consumption. That is probably because everywhere I've worked, one of the first things I make sure works is a way for the source management, bug tracking, and release management systems to reference each other. That way, the internal change log has references to the bugs and patches. Curious what the code change associated with something is? Click the link and look at the diffs.

Re:Change logs matter

[Cenan]

Not only that, but when something goes wrong after upgrading something, it's useful to be able to say "ok, what's changed since the last version...".

No, you do that before you upgrade and you use the changelog to determine whether you should upgrade at all. If you're doing it in reverse, its your own damn fault.

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?

Summarize

[saleenS281]

While it will take more work, posting EVERY change is completely unnecessary, and oftentimes unhelpful. The publicly released changelog should include human-readable summary's of bugfixes and new features. If a customer asks for more details about a bugfix, feel free to give them the unedited version as you see fit. A changelog should NOT be a git history. Information overload is oftentimes less helpful than nothing at all because someone may spend hours to days sifting through it all only to figure out what they were looking for isn't even there.

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.

Re:Not exactly cloud, but kinda

[bwcbwc]

Those are called release notes.

Unless it's an extremely specialized application that requires the customer to have expertise in a specialized field, most customers will be perfectly happy with release notes. The gritty details about changes are mostly needed for things like changes to an API, changes to an algorithm that affect calculations, etc.