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.
*after* being acquired by dell. If you've worked with that equipment, you know what I'm talking about.
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
Bad software will still be bad regardless of the change logs.
Quickbooks has a change log, yet I still very much dislike it.
http://support.quickbooks.intuit.com/support/articles/INF21754
*shrug*
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?
I started a company rather than went to work for a company who just didn't get it. Everything we do revolves on putting it out front for everybody to see. There are no secrets. We've been going strong for a few years now and the major difference is I picked a business model that worked. One where I wouldn't have to put profits before ethics. All at the same time my company does nearly the same thing the company I turned down a job over- and eventually went out of business.
The moral of the story is you shouldn't work for a company that sucks. And yea... I make significantly more than most slashdoters.
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.
Change logs indicate that the software is still being "maintained", whatever the hell that means. We only publish changelogs with very basic info. "Added this feature" "documentation improvement for this module" or "bugfix for something that our customers have mentioned online." If good customers ask for the real changelog, we'll give it to them under an NDA. If shitty ones ask for a changelog, we point them to the one/two liner. YMMV
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."
Slashdotters should know a scam when they see one.
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
I have 2 vendors that my company works for that drive me nuts with the lack of change logs. One posts change logs once a year or so, but has a dozen or so versions released annually. A call to tech support usually confirms that the changes don't affect us and aren't security related, but it's a pain to ask every time. The other fixes and changes a bunch of things with every release (and always breaks a few features that have worked for years...), but only documents a few trivial fixes & enhancements each time. I'm evaluating replacements for both vendors' products.
It is certainly useful to the person who filed bug 1234 to know that bug 1234 was closed in release number 5.7.
But... is the rest of the info in your issue tracking system formatted in any way that will be useful to a customer to read? At many of the places I've worked, we get issues with titles like "page formatted wrong, see attached screenshot". That is a pretty useless thing to automatically cut and paste into your spreadsheet. And severity reflects your internal judgement of severity, which may or may not bear any relation to severity-to-customers; something that is stopping other engineers from doing their work today is a Severe Bug and should be marked as such in your tracking system, but if it didn't get into the wild, customers don't need to know it ever existed. Similarly, we often check in code with placeholder text and file an issue to replace the placeholder text with approved final text; why would you ever want to show a customer a changelog that included the issue "replace placeholder text from initial checkin of feature X with final text"?
So: Like anything that is going to be delivered to a customer, this should be run through someone who checks it for relevance, and translates it into customer-facing language. The customer doesn't need to know about issues that never got into the wild, and the customer should have issues that were internally phrased in engineerspeak (because the issue tracking system is designed for use by engineers) rephrased into something useful; don't say "fixed server error 57 on badly formatted JSON", say "Fixed bug that caused web page to hang when user hit submit button" -- the first explains to an engineer what the issue that they're seeing in the logs that needs to be fixed is, the second explains to a customer what the problem they might have seen in the past is that isn't going to be there anymore.
"Open and Honest" communication needs to be clear and relevant communication as well. Don't bury your users in a list of a thousand lines of jargon they don't understand because you think more is better; give them a more compact list of the actual visible to them changes that were made, with the important things highlighted and brought to the top.
If it's an open-source project where you are giving out the source code, give them things like actual file diffs and commit logs too, because maybe some of your users are engineers hacking the source too. But most users are _users_, not engineers.
What reasons are there to NOT put them in?
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.
This is going to happen no matter what you do. If the competition is going to slander you, they will one way or another.
Another question is: Should I have facebook/twitter for my company, if the competetion can use it to slander us?
The answer is: Even if they try to, if you keep vocal on these feeds and try to solve all the grievences that arise, people will see that you give good support - even to trolls - and the competetion will look like trolls when they try to slander you.
Closing off communication does not enhance people opinions of you - but it does help the competition in making people believe that you are not doing good things.
I'm of the impression that if something was a problem but is fixed, the changelog pointing out the potentially "ridiculous" problem should be more of a badge of pride for resolving it. That said, there's no reason everything has to be included in a changelog, and even fixes that are included can be carefully stated so as to work around anything capable of being ridiculed or revealing additional holes in security or quality.
Assuming your employer isn't a Dice Holdings, Inc service and has an understanding of the stuff that matters ... just post that.
If I was to dump out all the issues "fixed" in JIRA as release notes customers would see things like "Add [some build task] to Bamboo build plan" which is meaningless to them.
Call out the new features, and coalesce minor bug fixes into sentences like "Fixed issues in Tab X which, under rare circumstances, would cause Y to be wrong."
The most important purpose of a change log is to provide a "forensic trail" to try to untangle something that is not quite as it should be, and nobody quite understands why it is not as it should be.
Change logs are a communications tool that applies across people and across time.
I cannot even count the number of times that I or my team have faced a puzzling problem ("This should never have done this"), and by studying the frank, open, and honest change logs, we were able to spot the discontinuity in the evolution of the system.
Public change logs discourage the frank, complete, sometimes embaassing record that is essential for a decent forensic trail.
Since someone is worried about it, entries could be listed as "improved metafile handling" rather than "fixed horribly broken metafile handling". One could even institute a convention that all commits messages indicate the type of change by starting with the either "New Feature:" or "Improvement". Show the complainer a list of 200 new features and 500 improvements and they may see it's value to customers.
Barring that, as a customer I don't really NEED 1,000 entries. I might very well ask "what's new in this version?", though. Mark the 50 most significant ones and pull those for the changelog.
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!
I rely on a few software packages heavily. I am so delighted when I see the change logs, it makes me feel that it's worth my time to upgrade. I also get the feeling that the software vendor really cares about attempting to achieve 'perfection'. Also is a bit of an interesting read and sometimes a treat while waiting for the software to download. I'd keep doing it.
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.
If you have enterprise customers, then make the changelog available under NDA. Or just email it to key customers that ask, so that prospective customers never see it.
I was in a similar situation at a former company. When I got there, the CSV log file was generated and put into a file called release_notes.txt. A practice I quickly stopped.
Then it was a matter of taking the data form the issue tracker and putting into a release notes format. Working with the product manager and customer support, the list was whittled down to issues that customers reported and features that the product manager wanted to promote. The process would take some time, but in the end, it was worth it because customer support could reference the release notes when suggesting that a client should update their installation. And the product manager worked with sales to use the release notes to promote new features.
So, the question is what do you want to use your release notes for? If the goal is to be brutally honest with your customers and air all your dirty laundry, then keep including every item. But for most users, they just want the highlights. The important information about why they should upgrade to the next version.
I have spent 15+ years in IT buying, selling, and using all manner of hardware and software. When a vendor changes something, I want to know. It's the easiest way to quickly see if some weird problem you are seeing can be corrected by installing an update.
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.
Some company like to have put a lot of detail into the update notes even stuff like added this next to useless thing (default off) with a list of why it's next to useless and say it's not recommended to trun on.
And this was part of a bigger update.
Also some of updates due have stuff like fixed crash that some times happens when you do X.
Don't post them all at once, dipshit.
I know that the Open Source Vulnerability Databae http://osvdb.org/ love trawling through release notes and change logs for security vulnerabilities and fixes.
Aside from this I think it's worth reporting for greater transparency.
The OP asks "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?"
Do any such references exist? I don't know of any.
However, I can attest to having watched one vendor who screwed up multiple times [not a software project] in some pretty major ways, and even though we gnashed our teeeth and wrung our hands, the up-fornt honesty of this vendor to admitting to mistakes (which were ultimately fixed) was actually a big positive in its favor.
Honest communications, no matter how negative they might seem at the time, do wonders in building confidence between a vendor and a customer.
Trust.
It's earned from open communication, then living up to your word. No disclosure, no trust, no investment.
As an employee, my next question would be, if they aren't communicating with their most valuable assets (customers), what aren't they communicating with their next most valuable assets (staff)?
When I've had to support an OS or application I've generally found it helpful for the release notes for an update to contain at least a summary of bug fixes since the last release as a minimum. That is assuming that the comments are detailed enough to be helpful. I don't necessarily need to see them all, but at least the major issues. That can help you decide if you need it to fix issues you are seeing, or if it could effect you. If your software has different collections of bundles of patches, such as a large standard bundle and various individual patches, you can see if you need to go outside of the standard bundle.
One example - A number of years ago there was a Solaris patch that wasn't part of the standard bundle, IIRC, that was needed to fix a problem that occurred only in certain advanced math functions on Ultrasparc III processors. If you were only doing generic database or web work you would be very unlikely to need it. But the applications we ran were very likely to be affected. So, seeing that, I grabbed and applied the patch where it was needed at my first opportunity. Not having a fix list would have prevented me from being able to make that choice and we would have taken a performance hit.
much of left-wing thought is a kind of playing with fire by people who don't even know that fire is hot - George Orwell
I like to give my users a fairly high level changelog when putting out an update to something I've been working on. Usually its to call attention to new features or important bug fixes. However, I don't go into too much detail, lest I overwhelm or confuse them. Of course I'm also working on something used by average people, not IT admins.
Also, many of the changes tend to be things never directly visible to the user. These things include bugs fixed in core parts of the app the user is only vaguely aware of or updates to data formats and network protocols. Even if changes are visible to the user, sometimes they're simply too minor to call attention to them.
Mostly, I like to give my users a reason to want to upgrade, and to know that I've actually done something in the latest update.
not posting change logs is going to all but disqualify you from consideration from many shops, unless your offering is the only one that can work, or none of your competitors offer change logs. how can anyone manage a deployment to hundreds+ or thousands+ of users without knowing what is going to change.
the alternative is vastly longer deployment testing, since instead of testing what has changed and things related to it, you are essentially doing a ground up test of every single function used every way that is important to the customer.
either that or install and pray.
Snowden and Manning are heroes.
Really? So, first off, it's not even *because* the software has been cast in a bad light or faced ridicule. It's "fear of" these things happening. And then you have to wonder exactly what things would "[put] the software in a bad light" or "[risk] ridicule"
For the former, I can only imagine nefarious things of which having a change log to confirm "Inserted Backdoor by request of NSA" or "Inserted Google Adware", of which I'd say it's the nefarious things that are at issue and I can only foresee the clear attempt to hide now future plans to do such things in such a move. For the latter, even the most ridiculous mistakes are tolerable if you're open about them and even include a rather curt "apology"--"Fixed a stupid typo, granting root access". That your competition may point at them, I can only say (1) you shouldn't cast stones in glass houses--and I can only foresee that that's precisely what it'd be and (2) you shouldn't trust anyone who is so quick to point out the mistakes of others as if *they* haven't done worse--most probably hiding or never having a change log which just highlights the point of how they try to attack your open honesty because they have little more than secret deceit.
Put another way, the only thing you have to fear is things you have things to fear for good reason. Yes, a bad press release and some media magic can give your software an unwarranted black eye, but there's nothing magical about having or not having a change log that will prevent that. And the best response to such a thing is precisely to shoot back *with* said long open record that shows not only how open and honest you are but how said media is incompetent precisely *because* you have said long open record. So, I'd have to say, this is all either some level of fear based reaction, some bullshit from someone with a possible nefarious agenda, or just something else equally stupid--change for change sake, perhaps, no change log included.
Now comes the real question: since you seem swayable by the idea that "fear" is a good reason to cut the change logs but not enough to not ask Ask Slashdot, are you going to be swayed by what I've written and shoot back with how stupid the plan is? Because then you're just as gullible to listen to me and Ask Slashdot in general. So, there. I've played the bad light and ridicule cards. :)
The change log is a product. It needs to be reviewed, readable to the target customers, and compliant to any necessary contractual, legal, or regulatory disclosures with the appropriate disclaimers. It should not reveal any trade secrets, third party confidential information, violate any vendor NDAs, have any unprofessional remarks about the customers, etc.
It sounds like the problem is you're putting out crap change logs using an automated system to copy things from the issue management system. Do you have policies in place to make sure people don't put crap into the issue management system? Are things being reviewed before the change logs are being put out? Is it being vetted by the necessary product/legal/regulatory folks to make sure nothing is in there that is going to bite you?
If a company published a crap product, then it will get bitten. When a company gets bitten, it's instinctive reaction is to stop putting out change logs to stop getting bitten, because that's the easy, lazy, doesn't take more effort answer. Asking "Whether or not change logs are a good idea?" is the wrong question. The right question is more "Okay, we got bitten because we put out crap change logs. How do we stop putting out crap?"
The answer to that question is generally something called 'Hard Work'. If the company isn't willing to put in the effort to make a good change log (appropriate policies to capture the relevant changes, tech writer/tech doc support to clean it up, manager-level review to vet it for compliance, etc.) Then, yes, it may make more business sense to not publish anything rather than to publish garbage. It's not a matter of whether or not change logs are good or bad -- good change logs are good, bad change logs are bad. The question is: How do you generate good change logs?
A log file like you would find on firefox's website is too long, boring and only organized for programmers that care. Which is the point, who cares? It depends entirely on your demographics. If you're building a website, logging clear, user-friendly changes can give the users more excitement when browsing the website. Not many offer them but when they do, it's either going to be easy to read or part of a database which the latter is not as friendly. If you're building a game, this is a must-have for sure. I read every improvement for the games that I enjoy. Any game that say "we updated the game from 1.4.2 to 1.4.64" without mentioning anything even on their forums are douches in my book. Many consider these logs like easter eggs. People tend to love them, but it depends entirely on what you're working on and who's your audience. In the end, people normally don't negatively judge software because it needed an update under normal circumstances. But if you pull a Nintendo and release hardware that immediately needs a 2gb update to play any game and most people tend to not have internet or very slow internet -- it becomes a problem. List what's important to the user of your demographics. The minor stuff can just be logged as "56 other minor improvements" or whatever.
+1000 to all of the above.
OP should quit the company. There's so many software companies hiring right now. The company clearly doesn't care about the customers' needs. I like having access to change logs, and my company's customers do too. It's a trivial taste to add to an existing change log. Most of the time you just need a single sentence that explains quickly what was done. It's not a big deal to make, but it's a big deal for people who rely on that software. Seriously, he should quit. The company is clearly hiding something.
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.
Yes, and every change log should say, "Dude, I'm like too drunk to remember what I changed!"
Two reasons not to publish raw logs like this... (1) Security vulnerabilities in previous versions, unless you guarantee all your customers have updated, and your release notes follow days after a release to give them a chance to avoid being zero-dayed, and (2) Telegraphing new product direction by either the comments themselves, or in such a way that the changes in aggregate allow it to be inferred.
Either of these things will give customers the opportunity to bitch loudly, and even if you have 10,000 customers, 2 of them bitching loudly can lead to weeks of unnecessary meetings.
We encountered the same problem, so a few years ago, we started running two changelogs. One of them is the full changelog, with every ridiculously miniscule change listed. This is made available to customers, but not promoted to them.
The other is the 'enhancements only changelog' - or what we colloquially refer to as 'the readme'. It only contains feature enhancements or significant bug fixes.
What are you trying to hide?
If the main factor behind it is indeed fear of ridicule, this company has other problems, probablya new boss who doesn't understand tech very well.
We should call this practice stability through oscurity.
My first program:
Hell Segmentation fault
If that's you, you guys have some real whoppers. Pretty sure I saw a change that fixed the inability to recover data (whoops). No wonder you want to hide it...
Absolutely. I ran into a kernel bug, which I helped fix. Now when installing a distro kernel I can check the changelog for my name to see if the bug that effects me is fixed in that kernel. I've done the same with firmware updates, like checking a RAID card firmware to see that it had a RAID 5 performance fix that effects me. For those things, a complete changelog is good.
For the main software I work on, the users normally want to know about the top 2 - 4 biggest changes.
Please. if there is a piece of software that I am using, the only reason that I *want* the changelogs are to see if it is worth upgrading and risking other bugs in order to fix the issue I'm stuck with. If there's software that I don't feel a horrendous burden from using it; I'd still like to know what has changed and why I should grab the newest version vs "misc bug fixes".
I worked in a large financial services company in Switzerland. We were one of the most intense users of a particular risk & control application. We understood each corner of this application and with each new release we analysed each change in detail. This was necessary to weigh-up the value of upgrading or not, or timing the upgrade appropriately. Some seemingly insignificant change could be a show-stopper for our users.
Unless the customer has a claim from you that "No Such Bug Exists, It Is Your Fault" and there is a previous or concurrent report in the changelog of a bug doing just that fault, AND that your software is sold under a far more generous and fair EULA than any shrinkwrap software in the world (and most bespoke or "enterprise class" software too) that gives redress for losses that are not limited to the value of the software.
Absent those precise coincident factors, there is no liability.
And if you're going to go "But you can sue for anything", that statement doesn't require changelogs either for it to be "true".
Sorry, where did the OP say "just slap that bugger on the production system"?
They didn't.
But if you put it in, it falls or fails or drops a bug.
Then you look again to see if there's any clue based on what it says when it falls over and what the changelog says, and then discover that there's another bug or some secondary software you have from elsewhere relied on a bug as a feature, or coded around the bug and needs updating.
The main reasons for pulling the change logs was the fear of putting the software in a bad light ...
A lawyer got to them and told them they were exposing themselves to liability. Simple.
Changelog is the best way for user to find out about new features and bugfixes. If they don't know about them they don't use new features and don't get rid of their obsolete bug workarounds. If you don't post changelog you make entire program less useful and the work that went into making the update is partly wasted.
This is an ongoing problem for my work. People who refuse to write changelogs often say "read the code, becuase they documentation can be wrong". What I've found is that if their documentation is that wrong, their code is usually even worse. Just reading what the code does will force you to replicate fundamental errors, to preserve unstated API's. In such cases, the change logs or revision history are invaluable, to expose why particular features were altered and when and by _whom_.
If software hs good git logs, or other change control logs, a pointer to those rather than explicit change logs is often enough for my work. But the change logs of packaging systems, such as .deb or .rpm, can provide invaluable information about the changes in the packaging. And the _packaging_ is often not in a public git repository.
Change a few trivial things, don't publish changelogs, advertise a new version, do it as often as you can and sell tons.
I'm a developer support engineer for a company that sells several SDKs - It is absolutely invaluable tor our customers (and ourselves) to be able to see the change logs as they're depending on our product to work in certain ways and could be interacting with dozens of systems/components.
I can't tell you how many times I've found that a claimed bug in our product was actually an issue in Weblogic or Websphere or Tomcat, etc.. that was corrected in a given fix (sadly, its often a case of customers coming to us and saying "this is a bug" and us diggin in only to find that yes it was a bug in that outdated version of the web application server they're using and they should have been doing their homework..
So both our own change logs and those of others are absolutely crucial in troubleshooting problems.
My personal $0.02: saying "here's what was fixed and when is not going to draw ridicule. However, having your software be a "big magic black box" is likely to alienate highly technical customers.
The Digital Sorceress
We would only publish change logs that met a certain criteria. Usually user submitted rather than internal changes. We would also create a change log per release, meaning we wouldn't just keep adding to it and sending the whole shebang.
Uh, reading is fundamental. OP isn't suggesting anything, it's cowardly management that puts covering their own asses over providing a quality product.
Never underestimate the power of stupid people in large groups.
Oh. I thought we were asking Slashdot to publish change-logs.
Never mind.
You are welcome on my lawn.
Not only do you tell me every change you make, but my engineers examine and audit all of your source code, and then we build it on our build environment for security reasons.
The issue management system usually includes two fields and one check box. One internal text field that includes information about the issue in great detail aimed for the core developers, and another text fields which includes simplified information about the issue targeted for the end user or management, and then a check box which specifies if this issue should be publicly visible. Usually an issue has both fields filled out and the check box checked, but if an issue is set as private it's usually because it concern a security issue, it's a really minor fix or it's a major embarrassment for the company :)
Comment removed based on user account deletion
When I first started working in IT, back in my early software days (as a tech writer), we did assemble a release report out of the defect tracking system, but then groomed it so that the descriptions were meaningful, and they communicated what the customer would actually see a a change. So many software changes don't leave much of a trace or evidence of a change at all that at some point you need to focus on the things you fixed/enhanced that could be appreciated. Occasionally, when there was a meaningful grouping of individual changes around a particular feature or piece of functionality, we were better served by an umbrella description that spoke generally about a swath of modifications and the area of functionality they affected. Further, we would "sanitize" (ugh, I hate that word) the descriptions so that they did not speak explicitly about protected IP in a way that would permit a casual engineering user to write their own stuff using the description as a template. It was also necessary to moderate the tone of individual defect reports in the summary to ensure that they did not come off as alarmist or use hyperbolic language -- you don't want to send out a report that says "Bezier curve clippings, when extended outside sections of the layout area, cause catastrophic, random, immutable, artifacts to appear in layout prior to full system crash" when it's a problem that (while bad, and fixable) doesn't happen in most situations and is only reproduceable if you use the tool in nonsensical ways. We used to have a couple layers of editorial review by the development management and sometimes legal if there was a sticky topic, but this was more to check work than to artfully craft anything. I had to help write release notes thereafter as a developer and as a manager, and the spirit is the same. If there is a bug in your stuff, your user community has probably already shared it with the world anyway, so acknowledging faults and fixing things is part of the virtuous cycle. You can actually gain user trust by demonstrating that you can successfully identify and promptly fix issues as they come up. Sales can be helped, too, if you had to solve some specific problems (or add functionality) before a customer will make a purchasing decision... they can recognize that their voice is being heard and the product is being maintained in a way that is attentive to their needs. All the same, there's no reason to shoot yourself in the foot in addition to having to fix your problems or make your enhancements.
.. pa-ra-bo-la, pa-ra-bo-la, 2 pi R, 2 pi R, where's your latus rectum, where's your latus rectum, 2 pi R
It depends on what the software is.
If I'm playing a game, the changelog is often "exploit closed, new content added" and most of the time not revealing that an exploit was closed causes malicious hacking to change their tactics. So in a game environment, the types of things you want to reveal are bug fixes that improve or balance things to the developers intent, or based on feedback, and avoid listing off specific bugs that were closed. eg instead of "closed an exploit" it becomes "rebalanced feature", which signals that the exploit was not a bug but was rather the players were using a game mechanic in a way that the developers didn't consider. I've seen this happen a lot in MMORPG's and often the subsequent whine about a game becoming too grindy when such exploits are fixed.
In general applications, the bug fixes can suggest a certain level of incompetence on the part of the developers if the same part of the application is repeatedly fixed for similar bugs. For example Apache, PHP, and MySQL, which many internet sites use, is often not updated except to solve exploits that are in the wild. Needlessly upgrading these three applications leads to a lot of downtime if underlying components (cURL, libxml2) aren't updated, or the OS (eg CentOS, RedHat) doesn't push updates first. RedHat/CentOS is still using Linux kernel 2.6.x , and as a result most Cloud Services are running on Linux 2.6.x kernels. If you try to upgrade a Linux kernel, generally it will break every single thing in the operating system. So as the story goes, you do not update the Linux kernel if there's not an exploit in the wild, you do not update apache/nginx unless there is an exploit in the wild, and you do not update php unless there is an exploit in the wild. PHP's 5.3 to 5.4 to 5.5 upgrades is driving a lot of updates to CMS systems like Wordpress and vBulletin that used poor coding practices due to PHP for some reason deciding to depreciate functions. Why depreciate anything?
This again goes back to the changelog. There is an entire PHP->Wordpress->Themes/Plugins arms race caused by PHP depreciating things, which in turn causes wordpress to depreciate things, in turn rendering various themes and plugins broken, and the people who use them cry foul because those modules have since been abandoned. The developer of "Comicpress" was pulled a fast one on his customers by bait-and-switching ComicPress to 2.9.x to his Easel project, resulting in pretty much everyone who didn't read the changelog having their site destroyed because the upgrade process erased all the php files to the previous version, including all customized changes that were in child themes.
Like when you think about it. Apple and Microsoft do have one large advantage over Linux, in which all the minimum functionality is "in the box" and the functionality doesn't suddenly end if Apple or Microsoft decide to cease supporting it. Linux on the other hand is completely broken and you're often forced to upgrade the entire base operating system just to get minimum functionality because no software will run on "old libraries" FreeBSD is somewhere in between, where you can usually use the "on disc" packages with the operating system as-is, but you'll be forced into the same patch arms race if you want to install anything that isn't on the disc.
So should you publish a change? yes. Will people read it? Few do. A changelog is more of a guideline as to "should I update" versus "working as intended."
If your software has a Linux port, then yes put out a changelog, because it is a huge pain in the behind to update the software version if the changes do not affect the use case of the software.
My clients still use php 5.3 because upgrading 5.4 will break the wordpress sites.
In the interest of openness and transparency changelogs should be published. Also they tell users why they should upgrade. Publishing them might show that you made mistakes but admitting them makes users think you are humble, honest, acknowledge them and want to fix them. Not publishing looks arrogant (upgrade because we say so) and too stuck up to admit your mistakes.
Some people think we're crazy, but on the game "Card Hunter," we publish all of our check-in messages on Twitter.
Here are some of the benefits:
Obviously, we make an effort not to post things that are going to compromise our security.
Has there been a downside? It hasn't bitten us yet. There is usually no reason to hide what technologies you are using, unless you are using something that is highly vulnerable, or you are making other bad choices. Don't do that. There is no reason to hide that your software has bugs. Everyone knows you have bugs. It's only shameful if you aren't fixing them.
Are we really crazy?
Change-logs should be strictly for internal use! 1) Log entries will contain technical shorthand that is meaningless to novices. 2) Opening these logs up exposes the company to all kinds of liability. 3) Do you think most people want to wade through mostly trivial and redundant entries? The proper forum to introduce meaningful new features to the public is in a blog. It goes without saying that this blog should be actively maintained and have at least one person whose sole job is maintaining it and filtering information from the technical teams, packaging it for public consumption.
'He who has to break a thing to find out what it is, has left the path of wisdom.' -- Gandalf to Saruman