Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
93 lines (48 sloc) 5.96 KB

Is it worth reporting an obvious and trivial documentation error?

A few days ago I had to look something up in the Spring Data MongoDB documentation. I wasn't sure which annotation to use to determine in which collection an entity should be written. I found the explanation for @Document, which was obviously what I was looking for:

Trival and obvious documentation error

So that's how it works! But what does the description say?

[...] where the database will be stored.

This is obviously wrong. It's not where the database is stored, it's where the data is stored. Small mistake, not nice, but not tragic either. Who cares?

At that moment I took care of it. Why shouldn't I draw someone's attention to it so that the error can be corrected? Such errors annoy me myself and I can also imagine that the author of the documentary is happy to be made aware of such errors.

Said & done. I know that Spring Data people listen to Twitter and first "reported" the bug there. My idea was that a maintainer just makes the necessary commit quickly and the job is done.

FrVaBe tweet

As feared, I was advised to provide a pull request for the fix. So the reporting would bit more complex than I thought but I prepared the pull request. Because the fix was so trivial I could do it completely in the GitHub user interface. In the pull request description template I got the hint that there should be a corresponding Jira Ticket. Pooh,...

Spring Jira; I once have already registered myself but the old logon data which I could remember, did not work any more. Attempts to restore the account failed and I finally created a new account and open the JIRA ticket DATAMONGO-2361.

Back to GitHub I noticed that the Spring Data MongoDB branches all follow the naming convention 'issue/DATAMONGO-xyz' and therefore I created a new branch also following this convention. And finally the pull-request was set up:

#787 - fix @Document description (DATAMONGO-2361)

Quite quickly came the request to sign a Contributor License Agreement (CLA). I can understand that, but before I sign anything I want to read and understand it. So the whole thing will be a bit more elaborate. As you might expect, I had a bit of a whinge on Twitter, of course.

CLA Mimimi Tweet

The moaning was successful! Mark Paluch (Spring Data Project Lead / @mp911de) released me from the CLA. The fix is too obvious for me to hold any property right on it ;-)

But what Mark did now? He changed the pull request title:

 was: fix @Document description (DATAMONGO-2361)
 new: DATAMONGO-2361 - fix @Document description.

Why? If you take a look at the Spring Data Mongo DB commit history you will understand why. All commits follow the naming convention

<JIRA issue> - <description>

This means that there is also a Jira issue for every commit. No commit without issue! And strong adherence to the conventions. That impressed me. And since I'm not only complaining on Twitter, I also praised it.

FrVaBe pedantic tweet

What should I say; a small conversation with some Spring maintainers arose out of it, which extended my knowledge horizon again a little bit.

issue label in github comments

Mark Paluch (@mp911de - which I mentioned already above and who took care about my pull request), Stéphane Nicoll (@snicoll), Jens Schauder (@jensschauder) and Florent Biville (@fbiville / here) - thank you!

To top it all off, my tweet was also retweeted by Senior Principal Software Engineer Oliver Drotbohm @Pivotal (@odrotbohm) and even our local (Aachen) Java Champion and my friend Michael (@rotnroll666) has mentioned the contribution. What a day! ;-).

Finally, the pull request was even merged as well. And I contributed to the Spring Data MongoDB project (by deleting four characters). How cool is that?

pull request Merged

For me, the fix at the end was not relevant, but the look into the working methods of others and the small conversations and interaction with the community were worth every minute.

tl;dr

It was worth it (for me) because

  • an error was corrected
  • I got to know a project and a small part of its work process
  • I got in touch with smart people which took care of me and helped
  • I have benefited from a small discussion

final note

Getting in touch with people is sometimes difficult and I don't do it easily myself. Twitter often makes it easy, but there are other ways. Many of the people mentioned here have already visited and presented at EuregJUG, for example. Take the opportunity to visit a JUG or a Meetup near you if you feel like making new contacts. It can be worth it.

Edit: Thanks to Josh Long for mentioning this little post in This Week in Spring - September 24th, 2019

You can’t perform that action at this time.