Add {LICENSE,COPYING}.* and {ChangeLog,CHANGELOG}.* to Files by default

[postmodern]

As with the convention of adding README.* to additional Files, so should {LICENSE,COPYING}.* and the ChangeLog files. Including the LICENSE file(s) is just common sense. Including the ChangeLog is incredibly useful, as you can link to specific releases and use YARD links in the ChangeLog entries.

99% of my ruby projects contain these files and ore adds them to .document by default. It would be DRY if YARD recognized these common files.

[lsegal]

Following up on discussion from docmeta/rubydoc.info#79:

all files should have an extension. MRI may not be the best example of common YARD usage, as YARD is primarily used by gem authors

"All files should have an extension" is a dubious claim. YARD has extensionless files. By that standard, YARD itself is not common usage of YARD? It's a fairly common UNIX standard to name plaintext files without extensions. UNIX conventions are fairly common in the Ruby community.

Including the LICENSE file(s) is just common sense.

I don't know that listing a complete license file is really that imperative to most projects. Many projects list "BSD" / "MIT" / "GPL" in their README and that's good enough from a documentation standpoint. The LICENSE file is a product of source distribution and attribution, not documentation. We could go back and forth on this, but:

1. YARD has always had the approach of "explicit is better". Documentation should be an opt-in activity, not opt-out, otherwise you end up with with a tool that shows you tons of data, little of which is actually useful (like RDoc's listing of source files as primary artifacts). Not all textual data in a source tree is equally important-- project owners should not only be diligent about what to show, but also what is not worth showing.
2. Support for READMEs should not be seen as precedence for this request-- it was only implemented for RDoc parity a long time ago. If I were doing things over again, I would refer back to point 1 and leave the feature out.
3. If the issue is that not enough people are adding these files to their docs, educate them on the importance of including these files in their documenting. Adding defaults so users can continue to ignore the state of their docs does nothing to improve documentation in the community. Specifically, if a gem author isn't documenting their ChangeLog or NEWS file at all (with no equivalent doc), it is likely indicative of a much deeper problem with the gem's docs. In short, this addresses the symptom, not the root cause.
4. Finally, on a technical note, and likely the one bearing most weight here, supporting this arbitrary and ever-changing list of conventional filenames is a huge maintenance headache. We get enough bug reports / compat issues with just supporting READMEs that I actually wish I could rip that support out (see point 2).

[postmodern]

@lsegal "all files should have an extension" is not a dubious claim, it is a best practice. a) the extension denotes the format of the contents b) it makes it easier for users/developers on Windows to work with the files. The only files that do not need an extension are binary files and block devices.

It is important to include the LICENSE file(s) as the author may have made modifications to the original text. The license file also contains the copyright holders and dates, which are not available in the gemspec. Additionally, specifying BSD or GPL in the gemspec is not enough, as there are multiple versions of those license. If you are worried about LICENSE files bloating up rubydoc.org, the majority of gems use the MIT license which is 1.1K in size. Even the GPL's lengthy COPYING.txt file is only 35K.

Finally, on a technical note, and likely the one bearing most weight here, supporting this arbitrary and ever-changing list of conventional filenames is a huge maintenance headache.

I am proposing the inclusion of the following patterns:

• {LICENSE,COPYING}.{md,tt,rdoc,txt}
• {ChangeLog,CHANGELOG}.{md,tt,rdoc,txt}

Clearly, that is not an arbitrary nor ever changing list. It is two file globs. If users wish to add more files, they can open a Pull Request which you can review at your leisure.

We get enough bug reports / compat issues with just supporting READMEs that I actually wish I could rip that support out (see point 2).

Could you list some of these bug reports to help give me a better idea? It sounds like that is a separate issue, which might be solved by refining the logic that processes additional files. At the bare minimum, problems with processing READMEs should be considered a blocker issuer and not grounds for rejection.

[mpapis]

I'm all for LICENSE{,.*}, CHANGELOG might be nice addition, not sure if it has to be part of the documentation.

[lsegal]

Clearly, that is not an arbitrary nor ever changing list. It is two file globs. If users wish to add more files, they can open a Pull Request which you can review at your leisure.

It's "two globs" until we get those pull requests that you acknowledge we would be getting-- that is the issue here. The problem is that this proposal changes the user's expectation such that YARD now manages exposing the conventional filenames of the month as a default. This opens a door that leads to said arbitrary list / maintenance woes. If CHANGELOG is valid, why not "CHANGES.*", which is also a fairly popular one? I don't want YARD to be in the business of deciding what files are important enough to be considered convention, precisely because it's entirely arbitrary.

Could you list some of these bug reports to help give me a better idea?

#777 is the most interesting / recent one that comes to mind, one that would repeat itself with every other file we add (and the fix for that issue is still just a bandaid). We've had others that weren't bugs but caused issues when users have multiple READMEs in different languages (like Sinatra), or Ruby's README.EXT vs README.other. In short, globbing is problematic.

[postmodern]

@lsegal let's be realistic here, ChangeLog and LICENSE are hardly "filesnames of the month". They are time honored conventions for projects, found even outside the Ruby ecosystem. If a case can be made for CHANGES then that can be added to the file glob as well. But let's not get derailed, we are talking about {LICENSE,COPYING}.* and {ChangeLog,CHANGELOG}.*.

[lsegal]

Marking this as WontFix. Adding these globs introduces complexity that has historically caused other compatibility issues when similar patches were accepted. I'm also unconvinced that a LICENSE and COPYING should necessarily be generated by default alongside API documentation, and I don't see a clear convention for a ChangeLog filename. YARD currently sticks to path/filename conventions used by RubyGems or RDoc (the latter for historical reasons), I don't think we should be creating new file structure conventions for Ruby projects. If RubyGems were to add some standardized ChangeLog/CHANGELOG filename convention, I would be willing to re-visit this.

Given how projects can opt-in with a .yardopts file, that is a reasonable path forward.