Skip to content

Commit

Permalink
remove Travis & Gemnasium badges from README
Browse files Browse the repository at this point in the history 
Rationale:

 - Who cares if the master branch is failing? Most users should be
   interested in tagged versions only, which we make sure are green.

 - Who cares if gem dependency status is "out of date"? We are using the
   versions of dependencies that work for us in testing.

 - The badges are visually noisy, especially when Markdown is viewed raw.
   Markdown is supposed to be readable.

 - I often view rendered README files for gems while offline and it
   helps if they load no external images.

 - It's time for badges, like/share/retweet buttons, etc. to fade away.
   http://informationarchitects.net/blog/sweep-the-sleaze/
  • Loading branch information
@mislav
mislav committed Jun 19, 2012
1 parent aa30071 commit ac1b537
Showing 1 changed file with 1 addition and 3 deletions.
4 changes: 1 addition & 3 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,4 @@
# Faraday [![Build Status](https://secure.travis-ci.org/technoweenie/faraday.png?branch=master)][travis] [![Dependency Status](https://gemnasium.com/technoweenie/faraday.png?travis)][gemnasium]
[travis]: http://travis-ci.org/technoweenie/faraday
[gemnasium]: https://gemnasium.com/technoweenie/faraday
# Faraday

Faraday is an HTTP client lib that provides a common interface over many
adapters (such as Net::HTTP) and embraces the concept of Rack middleware when
Expand Down

13 comments on commit ac1b537

@norbert
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1

@joshk
Copy link

@joshk joshk commented on ac1b537 Jun 19, 2012

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

:(

I think it is handy to at least have a link to the tests on Travis so people can see the current state of master

@rkh
Copy link

@rkh rkh commented on ac1b537 Jun 19, 2012

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1 tbh, I don't include the badge in my projects for exactly the same reasons.

@mislav
Copy link
Contributor Author

@mislav mislav commented on ac1b537 Jun 19, 2012

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@joshk I did add the text link to Travis in the "contributing" section. You didn't see it because it's in the next commit.

As for wanting to "see the current state of master": who, except the currently active contributors, would be interested in the state of master? As active I am in open source, I'm not currently actively contributing to most projects that I view READMEs of.

@joshk
Copy link

@joshk joshk commented on ac1b537 Jun 19, 2012 via email

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@rkh
Copy link

@rkh rkh commented on ac1b537 Jun 19, 2012

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As for seeing the current state of master, I use many gems using git sources, and seeing if tests currently pass and what ruby versions are supported is important for me. But as long as there is a link to CI then that is enough.

I use a browser extension for this.

@mislav
Copy link
Contributor Author

@mislav mislav commented on ac1b537 Jun 19, 2012

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Being a developer, I prefer not to rely on clicking on web images for important tasks. https://gist.github.com/1676577

@hone
Copy link
Contributor

@hone hone commented on ac1b537 Jun 19, 2012

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1

@jc00ke
Copy link

@jc00ke jc00ke commented on ac1b537 Feb 10, 2013

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why aren't badges built into Github itself? I'm not sure they belong in a README but it's nice to see them on the main page.

@sferik
Copy link
Member

@sferik sferik commented on ac1b537 Feb 10, 2013

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I’ve read @iaolo's “Sweep the Sleaze” and agree with much of it but I don’t think it applies directly to badges on GitHub. Almost all of his points are specific to social media badges on blogs and news sites. I'm not going to reply to every point, but here are some major differences:

Promising to make you look wired and magically promote your content in social networks, the Like, Retweet, and +1 buttons occupy a good spot on pretty much every page of the World Wide Web. Because of this, almost every major site and world brand is providing free advertising for Twitter and Facebook.

I have no interest in providing free advertising to Twitter or Facebook, but I’m proud to promote Travis, Gemnasium, and Code Climate. Even though these are all for-profit companies, they provide a valuable free service to the open-source community. I’m happy if other projects adopt these services because they see the badge in my README.

Did you know about the spying?

This doesn’t apply to PNG badges. It’s specific to Facebook’s Javascript.

Are you okay with slower loading times and bumpy scrolling?

Again, this is specific to Facebook's JavaScript. The Travis build status badge is approximately 1,586 bytes.

If you’re unknown, social media buttons make you look like a dog waiting for the crumbs from the table.

This is not relevant.

If you’re known and your text is not that great the sleaze buttons can look greedy and unfair (yes, people are jealous).

Again, irrelevant.

Now, to reply to some of your specific points:

Who cares if the master branch is failing? Most users should be interested in tagged versions only, which we make sure are green.

Almost all projects I work on have the policy: master should always be passing. If someone needs to do experimental work that breaks the build, do it in a branch. When a build is failing, the more people who see it, the better. This creates pressure to fix the problem quickly and may prompt someone new to get involved if they notice the failing build.

Also, as @joshk mentioned, many people specify git sources in their Gemfile. This functionality became critical during the recent multi-day outage of RubyGems.org. It is nice to be able to tell whether a project’s build is passing simply by looking at the README.

Who cares if gem dependency status is “out of date”? We are using the versions of dependencies that work for us in testing.

Just because a dependency works in testing doesn’t mean it’s a “good” dependency. New releases may contain security patches or API changes that require upstream changes. As with the build status, the more eyes on this, the better. If someone notices a dependency is out-of-date, it’s an opportunity for them to contribute to the project.

The badges are visually noisy, especially when Markdown is viewed raw. Markdown is supposed to be readable.

Markdown is two things. It's designed to be both a plan-text format that’s easy to read/write as well as a format that can be converted to HTML. If you don’t like the way images are formatted in Markdown, maybe you should use a different formatting language. I don’t think the conclusion should be to eliminate all images. Images are a feature of Markdown.

I often view rendered README files for gems while offline and it helps if they load no external images.

Specifically, what problem does this cause? If you’re offline, the requests should fail immediately and the images should be replaced by placeholder images. No big deal.

@sferik
Copy link
Member

@sferik sferik commented on ac1b537 Feb 10, 2013

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why aren't badges built into Github itself? I'm not sure they belong in a README but it's nice to see them on the main page.

@jc00ke That’s a good question, especially considering that build status is already integrated into GitHub pull requests…but until it’s integrated, I believe PNG badges are the best option.

@mislav
Copy link
Contributor Author

@mislav mislav commented on ac1b537 Feb 12, 2013

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re: sweep the sleaze: I agree it's not very applicable to our badges scenario, but I linked it because it makes a case against a practice people follow not because it has some proven benefits, but just because it's technically trivial and it's a fad.

I have no interest in providing free advertising to Twitter or Facebook, but I’m proud to promote Travis, Gemnasium, and Code Climate.

I'm also happy to promote those services (with the exception of Gemnasium, which is worse than useless), but I don't really believe that badges will bring them customers. The badges' primary purpose is to passively show the status of a project, and we don't even know their clickthrough rates.

Almost all projects I work on have the policy: master should always be passing.

Agreed. However, a constant green status still isn't a sign that it's safe to ride the edge. If you were using Rails master for an application, for instance, you would have a Really Bad Time™. Therefore I think we need to establish that we still expect our users to use tagged releases for most projects.

When a build is failing, the more people who see it, the better.

Members of the core team already get notified by Travis about failing builds. That's useful. What I don't think is necessary, however, is that users of a library be concerned about the state between releases. They look at the README as the source of description of a project, installation instructions, prerequisites, documentation. I don't want to tell Faraday users hey! the version that we're baking right now and which you're not using is FAILING!

This creates pressure to fix the problem quickly and may prompt someone new to get involved if they notice the failing build.

Sounds great in theory. I would love if someone would step in and made the Faraday test runner more portable. We have tons of false failures on Travis because of elusive and non-reproducible errors with threads. In practice, however, I can't imagine someone new stepping in and fixing our test suite because they saw a Travis badge. Deep, pervasive problems in OSS are more likely to get solved by people with perspective after a long-time involvement with the project—the same group of people that know how to monitor Travis directly and don't rely on a Travis badge to communicate state.

Just because a dependency works in testing doesn’t mean it’s a “good” dependency.

I would argue that a dependency that works in testing is the best possible dependency, because that's the only one that's guaranteed to work.

New releases may contain security patches or API changes that require upstream changes.

API changes in new releases of your library's dependencies are precisely the reason not to constantly upgrade those dependencies, because then you would have to constantly make changes to your library to compensate for those API changes.

For instance, if I wrote the "widget" library and used RSpec 1.3 to test it, I don't want to be notified of newer versions of RSpec, because 1.3 is what worked for me. In order to upgrade to 2.x, I might have to make huge refactorings of my test suite, with little benefit.

If someone notices a dependency is out-of-date, it’s an opportunity for them to contribute to the project.

This is the piece of advice that I most passionately disagree with. People submitting pull requests to bump up a dependency from its version "1.4.5" to "1.5.1" is as useful as email spam. I don't want to teach people to be doing this, just as I don't want to teach people that running a project through code lint or fixing trailing whitespace are valuable contributions either.

I often view rendered README files for gems while offline and it helps if they load no external images.

Agreed that this isn't a particularly strong point. But you have to agree that this looks kinda silly:

http___up mislav net_Mqw0

@sferik
Copy link
Member

@sferik sferik commented on ac1b537 Feb 12, 2013

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

API changes in new releases of your library’s dependencies are precisely the reason not to constantly upgrade those dependencies, because then you would have to constantly make changes to your library to compensate for those API changes.

For instance, if I wrote the "widget" library and used RSpec 1.3 to test it, I don’t want to be notified of newer versions of RSpec, because 1.3 is what worked for me. In order to upgrade to 2.x, I might have to make huge refactorings of my test suite, with little benefit.

This is the piece of advice that I most passionately disagree with.

Two points:

  1. In your example, RSpec is an internal dependency, so upgrading to the latest version doesn’t matter quite as much because it’s not holding back your library’s end users. If RSpec was an external dependency, you’d be preventing your users from upgrading to RSpec 2.x by locking to 1.x. This is sometimes a good decision, but it’s a decision I’d at least like to be aware that I’m making. That’s the value provided by Gemnasium.
  2. One of the things I ❤️ the most about software is that it tends to get better over time. New releases typically contain new features, security patches, bug fixes, and performance improvements. I think RSpec is a good example of this:

The latest version of RSpec represents hours upon hours of time improving and refining the library. The only update that costs you anything (in terms of refactoring your test suite) is upgrading from 1.3 to 2.0.

Of course, software doesn’t always get better with new versions—sometimes it becomes bloated and slow over time—but in these cases, I typically seek out a replacement instead of sticking with an old version.

For what it’s worth, I’ve been following this practice for years and it has served me well. I’ve engaged in many good discussions on the topic, including one with @michaelklishin and one with @qrush.

I’d also highly recommend reading this Heroku blog post on software erosion and the importance of keeping software up-to-date.

I understand that reasonable people can disagree about this, but circling back to the original point, I believe Gemnasium provides a valuable service and I’m always 😺 when someone notices that a particular dependency is out-of-date and offers a pull request to update it.

Please sign in to comment.