Ask Slashdot: To Publish Change Logs Or Not? 162
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?"
Your customers are lucky (Score:5, Insightful)
Change logs matter (Score:5, Insightful)
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.
Definitely (Score:5, Insightful)
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 (Score:5, Insightful)
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?
Run away...now. (Score:2, Insightful)
This is a boner move by your company. I've seen it happen before, and it's usually a sign of a failing company that fears reality.
Perhaps there was a recent management change? If yes, this is a sign that you've got a cowboy coming in with guns a-blazing and thinks he knows how to run a software shop... GTFO, while the gettin's good.
Fewer than 1000 (Score:4, Insightful)
Some OSS bug trackers have a 'relnote' field where people are to enter a release note if the owner feels it's something that ought to be communicated to the user.
As a user, don't bother me with stuff that will never effect me (did you refactor a class? - great, but I don't need to know about it) or I won't need to look up (did you fix a CVE or a spelling mistake?) but do let me know about changes that will affect my workflow, will offer me an improved way of doing something, or should cause me to go revisit results I've generated in the past (i.e. you had a bug).
Externally meaningful changes (Score:3, Insightful)
My employer produces a compiler tool chain for its products. Its release notes contain two major things:
1. A list of major customer visible changes.
2. A list of defects fixed
The first represents our internal development efforts. It's written in terms of the actual features, how they affect our users, and how the users ought to use them. They are not written in terms of the series of commits that made the features happen. That would just be pointless.
The second represents the defects fixed in this (and recent) releases, as pulled from the bug tracking system. If a customer filed a bug and we fixed that bug, that bug number and a brief description of the bug are in the release notes. Again, this is not tied to a commit stream that addressed the bug, but rather to defect reports that were closed by the release. Most of these defects come from external customers, but not all.
What's not in there? All the internal churn that got us from point A to point B. We distill it down to what the externally meaningful changes are.
Disclaimer: I am not on the team that produces the tool chain I described. I'm just a happy, internal customer of said tool-chain.
Summarize (Score:5, Insightful)
Re:Your customers are lucky (Score:4, Insightful)
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:Change logs matter (Score:5, Insightful)
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.
Not exactly cloud, but kinda (Score:5, Insightful)
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:Your customers are lucky (Score:5, Insightful)
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:Change logs matter (Score:5, Insightful)
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.
Re:Not exactly cloud, but kinda (Score:5, Insightful)
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.
Re:Your customers are lucky (Score:4, Insightful)
The change logs are for internal use; they aren't for your customers.
I'm not going to be one of your customers, then. I check the changelogs of every Cisco IOS update I deploy. If they changelog isn't published yet, I don't deploy.
I'm not going to add risk to my environment if all the new version did was fix bugs in features I don't use and add new features (with new bugs) that I won't use.