README.pod included in distribution
Grinnz opened this issue · comments
README.pod is included in the root of the distribution. This is discouraged (and a warning is produced under newer EUMM) because EUMM will install any .pm and .pod files from the root -- this one will end up at DBD/README.pod which is an unhelpful location and a namespace not owned by this distribution. It should be excluded from the distribution, only plaintext or .md READMEs should be shipped in the root.
Hello! In pull request #148 is a fix for this problem. README.pod will be now installed as lib/DBD/MariaDB/README.pod file. Similarly autogenerated manpage.
README.pod in top level directory on github is a starting point and provides details about project. Bugs in ExtUtils::MakeMakers should not be reason to stop providing useful files.
Could you please check that pull request if it fixes that problem?
I thought that the README.pod was intended for the github repo, not as documentation. If you want to make it a documentation readme, it should include:
=head1 NAME
DBD::MariaDB::README - ...
And also it should be stored in lib/DBD/MariaDB/README.pod, thus not needing this workaround.
My suggestion was simply to not include it in the CPAN distribution, leaving it for github, using e.g. MANIFEST.SKIP.
Is there any problem to have README file also in distribution on CPAN? I guess that downstream packagers for different Linux distribution would like to see some simple README file in released tarball.
Storing README file in different directory (like lib/DBD/MariaDB as you suggested) would not work. All software store README file in released tarball in top level directory. Nobody would be trying to find main README file deeply in some third level subdirectory.
@pali Note: There is README file in my distributions. But in form of text, not POD. I think you can add creating of README from README.pod and README.pod skip in distribution.
Is there any problem to have README file also in distribution on CPAN? I guess that downstream packagers for different Linux distribution would like to see some simple README file in released tarball.
Yes, README.pod specifically is subject to the ExtUtils::MakeMaker bug and cannot be included at the top level.
Storing README file in different directory (like lib/DBD/MariaDB as you suggested) would not work. All software store README file in released tarball in top level directory. Nobody would be trying to find main README file deeply in some third level subdirectory.
You are proposing to install it to DBD::MariaDB::README, so it should be stored at that location in the release, and also have the appropriate NAME section so metacpan displays it as documentation.
Yes, README.pod specifically is subject to the ExtUtils::MakeMaker bug and cannot be included at the top level.
It should not be affected after applying #148 change.
I guess my question is: what is the purpose of this readme? If it is for github, as I originally thought, then it only needs to be added to MANIFEST.SKIP. If it is documentation, then it should be moved to the correct location in lib/ and allowed to be shown on metacpan. If it is for github and the released tarball, but not as documentation, then it should not be installed.
It is top level README file like in any other software distributed in tarball and visible by as main page on github. Therefore it cannot be in subdirectory and cannot be in MANIFEST.SKIP (as it would not be included in release tarball).
I think the proposed solution is acceptable, if maybe not standard. It's unfortunate that we can't specify "use the general rules, but handle these particular files differently" - currently, one either uses the general rules, or has to specify the install location for each file manually.