Please provide a change log

I know, I know, it's all free software and open source - you shouldn't expect anyone to do anything. However, we do want our projects to succeed and we do put them out there in hope that it will be useful to someone.

So, you can be a jerk and provide a simple .pm file, without any documentation (because "it simply works"), no toolchain configuration (you "don't need any") and no tests (hey, if it works, it works, right?).

However, CPAN ain't like that. CPAN is (mostly) well structured distributions that adhere to community standards that include: building toolchain files, metadata to help CPAN indexers and installation applications, tests, documentation (in a standard format - POD), sometimes examples folder with sample scripts using your code, perhaps a GPG signature file to have content verified and - *gasp* - a change log indicating what each version added (and perhaps when it was released too).

I'm listed to the CPAN RSS because CPAN is my language and I need to know what's up. Whenever a distribution I use has a new version out I go over the change log and see whether I need to upgrade, whether I should upgrade (for a new feature or fix) or update my code (API change?) or the likes.

However, it appears some authors - which are hell of a lot smarter than I, with much more interesting projects - do not see the point of keeping a change log. Is it a difficult task? Does it disrupt their release flow? I've prepared the last change log entry of Dancer and I can assure you that it took less than one minute. Simply "git log", checking the messages, seeing what people did since last release and deciding what is worth mentioning in the log. That's it. It's even easier if you simply add an entry after doing a change.

Currently if you don't keep a change log, I have a hard time using your project. Simply because I have no idea what's going on there unless I check the source myself. To be completely honest, I don't feel like running diff (even though there's a relatively comfortable one in CPAN) every time you make a release.

Please oh please keep a god damn change log.

Thank you.

14 Comments

Hear hear!

Also, please make it something OTHER than a copy of git/svn/cvs/whatever's changelog deltas.

Seriously, things like this:
http://cpansearch.perl.org/src/CHM/PDL-2.4.7/Changes

Makes me wish you HAD NOT produced a changelog.

Changelog size: 345kb.

Who is ever going to read that?!

Every time a new upload of this hits http://frepan.64p.org , it produces a massive several page of changelog delta.

Sorry, but I stopped reading after "So, you can be a jerk and provide a simple .pm file"

Yeah, what a jerk.

Could we have these discussions without insulting or belittling anybody? If your second paragraph already contains an ad hominem covering an entire group of developers, do you think a good discussion will come out of it where both sides weigh in?

Actually, CPAN is like that. It's specific design goal was to have no barrier to entry so it was as easy as possible to upload code as soon as possible.

It's open source. You get to contribute when you find something you think that you can improve.

I think people should include change logs, but I'm not going to get annoyed when they don't (especially when so many change logs are useless).

"ignoring all community standards and common sense (tests out the window, documentation is missing, no readmes, no META data, no building tools)"

This takes experience, and a lot of reading. Do you think calling people jerks will motivate them to invest their time?

"and then swipe you for even suggesting they should do a bit more about their code, simply because it's free software and you should STFU for even suggesting it."

If you're using the same tone for individuals as you're using for entire groups of people I'm not surprised. Even if you made that restriction later in the post (which I don't know), or lowered down on tone, why should people continue reading after being insulted? After all, if I'm only a part-time contributor, the people who insult me for not investing even more time aren't really the people I'm gonna care about.

By the same reasoning, why publish this blog post at all if you can't make a point without insulting your target group?

"And I hate those kind of people that fake it as if they contribute when in fact they're just using the internet to store their code for them instead of actually "sharing" it."

They aren't faking it. If it's released, you can fork it. If it isn't, nobody knows it's there. Also, it stops being part of the DarkPAN and the code is suddenly discoverable.

Us full-time many-solutions-to-many-problems Perl developers sometimes seem to forget that there's a large part of people who are simply trying to solve their problems. Their main concern is to get something done, not to package something up nicely, or learn how to do it.

"I guess it's kind of like putting an encrypted dvd in the living room (which no one can use without decrypting abilities) and say you're "sharing with the residents". were you really sharing? I don't think so."

No, it's not at all like that. Nothing is encrypted, nothings hidden. It's more like getting a music tape without a song list. Or a used VCR without manual. Yea, it's more work for you. But would you insult someone giving you a tape or a CD without a songlist as a gift? I don't think so.

"Seems like you consider yourself in that group but I can assure you that you are not. If you wish to be for the sake of being offended - that's fine. My apology to you was that even though I wasn't referring to you, you were still offended."

I'm not offended, not even just for the sake of it. I do however argue for the sake of those that'll stop reading after feeling insulted. I and many others (probably including you, which is why I am surprised) have enough first-hand experience with companies and developers estranged from the core Perl community that my experience tells me this isn't the way to go about it, and that it might do more harm ("might" because of the problems with quantifying "harm").

As such, there's no apology necessary. At least not to me.

"I call them jerks and move on. My post was to those that aren't in that group, such as you."

And you've reached me. And I disagree, and highly value the work anyone shares. That'd be like only accepting donations above 100 bucks.

"This isn't my target group. My target group is everyone but them. And if they were my target group (which they aren't), I'd probably try to make a point without insulting them."

That was my mistake then. Although I'm not sure how you want to manage to not tell this message to the target group as well, since you've made it publicly.

"I disagree. Being able to fork is determined by more than just "having the code out". For example, the source could prevent it. More importantly, though, is that you still need someone who understands what you did, can read your code, comprehend it and fork it. That's not as trivial as you describe it. People are users first, developers second. A user uses, a developer forks."

How would the source prevent a fork? If you mean the license, AFAIK only Open Source licenses are accepted on CPAN.

And in my book, if you're reading CPAN, you're a developer. And luckily most of the source code on CPAN is written in Perl, so it should be able to be understood. If it isn't, then it might not be worth forking (yet). But you can't tell me you don't have more freedoms because of the release as you've had without.

"Adding a few lines of documentation here and there allow the code to be used, forked (if the license allows) and added to. It's not that great of a task and I personally don't understand why you're going out of your way to defend someone who's just lazy in writing 2-3 lines (in some cases)."

Because it isn't just "a few lines." First thing, which few lines should be written? What if the few lines aren't the few lines that help you?

Also, community standards are much, much higher these days, which is awesome. But it didn't get this way because of rudeness. Would you like to join a community that calls you a jerk because you're not yet experienced enough? Because for you it's a simple README (that probably wouldn't help anyway), for others it's a list of methods, or tests, or parameter declaration, or support information, and so on, and so on.

And as to why I am defending these people: You assume malice, I assume they don't know how or why to care. And because there's a large part that wouldn't care about speaking up, they will just stay away.

"True, but I wouldn't consider that as a whole lot of "sharing". I do believe that if you want to share, you at least have to make an effort to make it somewhat accessible to people. Some people don't do that."

They make it "accessible" by releasing the source. That's already an effort. They could also simply not cared at all and we'd have never known the existence of the Perl code. The people who don't do that are what is called DarkPAN.

"I wouldn't ask a person to know how to do everything, but I would expect him to make an effort if he claims to care."

And why is your amount of effort the right one? If they think they've already put up effort to dislodge the code from their internal code base so it can be re-used outside of their company, or have put in the effort of simply writing it, are they jerks because their understanding of (their) efforts is different than yours?

"A music tape without a song list is still usable in almost every way (at least the original purpose - to listen to it)."

A program without documentation is still usable in almost every way (at least the original purpose - to run it). The matter is that you don't know how to use it, or don't want to put in the effort to understand it, and you think it's the authors fault. Besides that, all analogies are false.

"Code, unfortunately, isn't that easy as most electronics and listening to a music tape. If you wrote a jQuery plugin but didn't add documentation on what functions it has, what it accepts, what it returns, how it works, what the hell does it do -- I wouldn't be able to use it in any way. I would have to read the source and hope that you wrote very clean understandable source and that I'm a good enough programmer to read it and figure it out."

And even if not, it would only mean you couldn't or didn't want to figure it out, so it's not usable for you. That doesn't have to be true for everybody.

With regard to electronics, I've seen enough people fail at configuring their VCRs or mobile phones that I'd like to disagree.

"You seem to assume it's just a matter of me not wanting to do more work. Sometimes it's work I can't do. Have you never seen a module that you had no idea what's going on by looking at the source? Is it always a matter of the user being lazy?"

Sure I've seen those kinds of modules. But why should I care? If I don't know what they're doing, they're not solving one of my problems. So worst case for me is that they won't be a solution, same as if they didn't exist.

"If someone gave me a CD that is encoded is some format without telling me even which format it is, what program could open it, what codec it is and I would have to search for something that will run it (and try to install different codecs) or codec checkers (that might recognize it or not) and have to spend so much time in order to finally be able to listen to the music on the CD, it would be a pretty lousy gift and I think you'll agree on that. :)"

I might, if the hurdles were anywhere near that high. "Not writing documentation" does not equate to "obfuscation" or "encryption."

Besides, there's lots of reasons for that CD format to be incompatible besides malice.

I was going to say that if you want to communicate “dude, you could make it easier for people to use your code” it doesn’t help you to instead say “dude, you are a self-deluding jerk”.

Then I saw this:

More importantly, though, is that you still need someone who understands what you did, can read your code, comprehend it and fork it. That’s not as trivial as you describe it. People are users first, developers second.

To which I say that you are always free to not use a piece of software you don’t understand. After this, what I get from your post is more along the lines of this: “You released some software! I demand that you make it easy for me to pick up in case it’s useful to me.” There is no basis for such a sense of entitlement. No one is forcing you to use it.

And then, I came upon this:

Code, unfortunately, isn’t that easy as most electronics and listening to a music tape. If you wrote a jQuery plugin but didn’t add documentation on what functions it has, what it accepts, what it returns, how it works, what the hell does it do – I wouldn’t be able to use it in any way.

And that has me just flabbergasted. Learn to read code. Seriously. If you cannot read code without crutches, you are deficient as a programmer. I say this even as don’t read other people’s code enough myself. (It is my one source of shame as a programmer that I should have done a lot more code lecture, and that I still rarely bring myself to.)

Don’t forget that one day the code you’re going to have to read will be written by someone else called “your own self from 5 years ago”.

"The comment entirely referred to people who aren't interested to make code more accessible to others, whether by my suggestions, community standards or common sense. This is a very limited group of people but I've already received at least one comment from a member of this group to an old post I made suggesting things you can do to help make your project more accessible."

First, please leave "common sense" out of it. I find it a weird idea that we should all share the same "common sense." In most cases it simply means "predominant opinion in the current group."

Second, I very well understand whom you intended to offend. I am trying to tell you that those won't be the only people who might be offended by this, because they'll put themselves in exactly that group.

Your intention is to say "rude people are jerks." Well, yes they are, but what else is new? I could also only guess if those examples are paraphrased or not. Personally, I have yet to meet a CPAN author who is rude just for the sake of it.

"Since this post tried to do the same (only suggest something which would help make your project more accessible), I was expecting to get a reply saying "fuck off, I don't owe you a changes log, or anything else for that matter". That's pretty much the comment I received by that person."

What does "pretty much" mean? Did you ask him for a changelog or did you tell him what "the community standards" and "common sense" are?

"This is the point of this post and it seems we dragged it into a completely different discussion."

Yes, I'm feared in many parts of the world for that power.

"That's a point I should make clearer: I was referring to those specifically that do it out of malice. People who know why to care but simply don't, and are being offensive to others who suggest people should care."

I think you overestimate the fame one gets from releasing stuff to CPAN. And I still don't get why they should care. "You already donated 150 bucks, you should make that an even 200" doesn't fly. They cared enough to release their code under a public license. If you can't approve of sharing their code as caring, what incentive do they have to seek approval by putting in more work?

"It isn't! It is merely a suggestion of an additional effort you *might* want to make *if* you care. It's not even necessarily *a* right one, let alone *the* right one."

Then why do you formulate your words in a way that suggests that you don't count less caring than exactly that much as not-caring?

I could even imagine some people wanting to share Perl code, but not wanting to be part of the community. And in my eyes they're welcome to that too.

CPAN always gave me the sense of "sharing is caring," and no matter what all our opinions, we always have that as common ground.

That’s a point I should make clearer: I was referring to those specifically that do it out of malice.

Whoa there. Malice? I don’t see how anyone can do personal harm to anyone else by the mere act of uploading something to the CPAN, no matter what that is. Repeat after me: you are always free to not use a piece of code from the CPAN.

People who know why to care but simply don’t

Writing a change log makes a package more approachable for users. But maybe the author simply doesn’t care about how many users their code gets or has? In that case, writing a change log would be extra work with nothing gained. Why should they care?

Of course, users should be aware of what they’re getting into when they try to use that author’s software – extra work, maybe a lot of it. But I’ll assume users are grown people who can make that call for themselves.

and are being offensive to others who suggest people should care.

I doubt anyone will get offensive if you merely suggest to them the benefits they themselves would get out of writing a change log. (“Hey, if you wrote a change log, that would it much easier for other interested people to use your software. And it’s not much work. I can help if you want. Think about it?”) If instead you demand it or even call the person a jerk for not already doing it – well then, what did you expect?

Wie man in den Wald hineinruft, so schallt es heraus.

(German proverb – “as you call out to the woods, so they will echo to you”.)

Leave a comment

About Sawyer X

user-pic Gots to do the bloggingz