github
Improve hinting about license file names
Code of Conduct
- [X] I have read and agree to the GitHub Docs project's Code of Conduct
What article on docs.github.com is affected?
https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/licensing-a-repository#determining-the-location-of-your-license https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/licensing-a-repository#detecting-a-license
What part(s) of the article would you like to see updated?
Determining the location of your license
Most people place their license text in a file named LICENSE.txt (or LICENSE.md or LICENSE.rst) in the root of the repository; here's an example from Hubot.
Some projects include information about their license in their README. For example, a project's README may include a note saying "This project is licensed under the terms of the MIT license."
As a best practice, we encourage you to include the license file with your project.
Detecting a license
The open source Ruby gem Licensee compares the repository's LICENSE file to a short list of known licenses. Licensee also provides the Licenses API and gives us insight into how repositories on GitHub are licensed. If your repository is using a license that isn't listed on the Choose a License website, you can request including the license.
If your repository is using a license that is listed on the Choose a License website and it's not displaying clearly at the top of the repository page, it may contain multiple licenses or other complexity. To have your license detected, simplify your LICENSE file and note the complexity somewhere else, such as your repository's README file.
Additional information
The zeek project was trying to understand why GitHub didn't properly link to their license, you can see it discussed here: https://github.com/zeek/zeek/issues/2521#event-8145487297
The quoted text above really only hints at LICENSE and README (and maybe at a couple of extensions to those terms). It's true that it does yield a pointer to the Licensee, but following that pointer involved reading the guts of its library which didn't sound pleasant (I'm fairly certain I've read it on occasion).
It'd be nice if there was more prose to help projects address the headaches described in the above ticket.
As a quick note, https://github.com/licensee/licensee/blob/main/docs/what-we-look-at.md#detecting-the-license-file is not particularly helpful, as the real answer (today) is https://github.com/licensee/licensee/blob/HEAD/lib/licensee/project_files/license_file.rb
It'd be nice if there was a webpage that the docs could link to that listed the files (or the patterns) that would be matched. Offhand, assuming that the file path doesn't change, the above isn't terrible (I'm relying on HEAD being more or less reliable).
👋 @jsoref - Thanks for opening an issue and providing all the additional context. ✨
I'll get this triaged for review! ⚡
👋 @jsoref Thanks for opening this issue! It does look like this article could use some reworking and additional information to clear up the problems you described. I think it would benefit from our team taking a closer look at it as a whole, so I have opened an internal issue for this and will close this one out! 👍
