Make License & Maintainers a XOR with Badges about standard-readme HOT 15 CLOSED

I disagree; badges are not the best way to display information across different mediums, and there are very few cases where having the license information above the metaphorical fold is important, especially with the current tooling around finding out which licenses your deps have solving that issue for most of those edge cases. Badges should be limited as much as possible, as they are a bit noisy and only really show up on GitHub.

As well, the License section can have more information than just the license - it should show the year, the maintainer or owner, and any other notes.

from standard-readme.

I think the important part is

tainers information (link)

link the badge should have a link to a LICENSE.md file that contains further image. Having the license above the fold is imho a matter of taste but the information that it provides (the link) should be sufficient.

from standard-readme.

That link is already a suggestion in the License section:

- Link to longer License file in local repository.

Maybe I am misunderstanding. I don't see why a badge is necessary on top of a License section, and I think that a License section should be mandatory.

from standard-readme.

Thats why I put it XOR .. either there is a license section or the badge. Freedom of choice?

from standard-readme.

Ah, that's a new word for me. Cool! Good to learn.

I disagree that you should have the option to not have a License section. Nothing is stopping you from having a badge too. I think one way is better (á la standard).

from standard-readme.

Just note that if I have to have a license section that I will drop the badge ^_^

from standard-readme.

Which badge? The License badge? :)

from standard-readme.

Yes. I will not add a license badge in addition to the license section. So: its XOR :)

from standard-readme.

Ahh. Ok. :)

Do you understand my reasoning for requiring a License section?

from standard-readme.

Tbh. not really. but having only one solution is a sound course of action. XOR's are tricky to begin with.

from standard-readme.

Going to come back to this in a bit. Reopening because this needs more discussion.

from standard-readme.

Ok. I think we agree on a few things.

First, we think there needs to be a License section in the README. This is not a given. You can have a LICENSE file with the repository, and you generally have a License section in the package.json or equivalent package manager file. However, these are a remove from the port of entry for your package: your README. Your README should have everything a normal human would want to read to understand how to use your package, how to install your package, and what to know before messing around with the files. The License name should be part of that.

Having a License section is the easiest way to display this information accurately, consistently, and with the prominence it deserves, I feel. The License name shouldn't be in the title, nor long description, nor Install or Usage sections - it's its own piece of information, with its own needs and wants.

You opened this issue because a badge would be another good place to put a license. I agree! If you are coming from GitHub, a license can be prominently displayed with little to no overhead in a badge. Badges are a good way to show information: they care colorful, they are small, they look nice, and they are above the proverbial fold of the the README.

However, I think that a License section is still needed, even if you have a badge. Why? Because it is consistent, and because it can give two more pieces of information: the year, and the license owner. Just saying "MIT" is not enough to really show what should be shown in the license.

The year is obvious: I am less likely to use a package if the year hasn't been updated for a long time, and I know that the community that code comes from has moved on to more developed and recent tools (for instance, an Angular package from 2012 is no longer relevant, and I might go and look for a newer package).

Names, however, are more important. Here is an extreme example: I wouldn't use a package that said "MIT © 0032ad Julius Caeser." Why? Because the licensing is clearly not serious. I also would try my hardest not use a package that said this: "MIT © 2016 ISIS". Why? Because I don't want to be affiliated with a terrorist organization. And here is a more common example; I want to know who holds the license, because it tells me what to expect from the software. If a piece of code is licensed by Facebook, I look very seriously at the code, because I know that Facebook has a history of removing the right to use code from people who disagree with it. This is non-trivial, and this information cannot be contained in the badge - but it belongs in the README.

Both of these things should be in the section.

I also want to stress that having a section makes the licensing information consistent. This is important, because I want to be able to look at a README and know where some information will be, and to be able to predict that. I also want to have one place, as a writer, to put some information. Having an XOR function for placing licensing information leaves me having to think about it. This is against the idea of standard-readme; make READMEs easier by removing the friction of writing and reading them.

Does that help clarify why I want to have a LICENSE section? Having an extra badge, of course, is OK.

from standard-readme.

Ok. Closing this. Let me know if you'd like to reopen/

from standard-readme.

Times have changed since I opened this issue. Actually, since Github introduced License detection my new policy has become to keep a license file in my folder and not mention the license in the readme. I am thinking to even drop the badges as they are duplicate when viewing in Github.

from standard-readme.

Yep. That makes sense to me. I still like having a License in the README, because ultimately it should have information in it that can be seen simply by catting it in your CLI, as well as through GitHub.

from standard-readme.