Slashdot Mirror
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?"
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.
"First they came for the slanderers and i said nothing."
I won't install an update without a change log.
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.
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?
The Christian Right is Neither (Christian nor right). See: Matthew 23, Matthew 25, Ezekiel 16:48-50
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?
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.
Different customers are going to feel differently, but in my experience doing releases, a different thing matters more.
The key is to make sure that each release is an improvement over the previous release. If you do that, your customers will be happy, and won't worry much, as you build trust and confidence over time. In your situation, if a particular customer requests the change logs, I would give them, but a general release is not important.
The real problems come when your releases break things. After an especially bad release, your customers might not be willing to upgrade for two or three years (see: Windows Vista). Make sure each release is better than the previous. That is crucial.
"First they came for the slanderers and i said nothing."
Does it have to be all or nothing?
Our software supports the hardware so we don't feel any palpable, fierce competition since we always lag the hardware improvements and those get top billing. Our users are interested in knowing the changes that are meaningful to them.
Since I use our change logs to significantly build our "brochure" touting reasons to upgrade, maybe you all can pare down change logs to the "best of the 1000" to say "20"... a list most can bother to go through.
That was Zen, this is Tao
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).
My God, it's Full of Source!
OUTSIDE_IP=$(dig +short my.ip @outsideip.net)
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.
Program Intellivision!
From where I sit there's no question: for compliance reasons we must be able to detail exactly what is being changed when we install updates to software. If we can't, then we have to re-certify the software from scratch before it can be deployed which is a fairly tedious and time-consuming process. Having to do that with any regularity will find us looking for alternatives.
As for a list of bug-fixes making your software look bad, remember this: I know exactly how long our unresolved-issues list is for every single bit of commercial software we use, and exactly how long some of those issues have been sitting there. That your software has bugs that needed fixed too isn't going to come as any great surprise to me. What will impress me is a) actually fixing problems, and b) being clear about what you're fixing or changing which minimizes the amount of work I get saddled with.
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.
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.