Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

README.pod included in distribution #146

Closed
Grinnz opened this issue Jun 27, 2019 · 12 comments · Fixed by #148
Closed

README.pod included in distribution #146

Grinnz opened this issue Jun 27, 2019 · 12 comments · Fixed by #148

Comments

@Grinnz
Copy link
Contributor

Grinnz commented Jun 27, 2019

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.
@pali pali mentioned this issue Aug 27, 2019
Merged
@pali
Copy link
Member

pali commented Aug 27, 2019

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.

@pali
Copy link
Member

pali commented Aug 27, 2019

Could you please check that pull request if it fixes that problem?

@Grinnz
Copy link
Contributor Author

Grinnz commented Aug 27, 2019

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 - ...

@Grinnz
Copy link
Contributor Author

Grinnz commented Aug 27, 2019

And also it should be stored in lib/DBD/MariaDB/README.pod, thus not needing this workaround.

@Grinnz
Copy link
Contributor Author

Grinnz commented Aug 27, 2019

My suggestion was simply to not include it in the CPAN distribution, leaving it for github, using e.g. MANIFEST.SKIP.

@pali
Copy link
Member

pali commented Aug 28, 2019

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.

@michal-josef-spacek
Copy link

@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.

@Grinnz
Copy link
Contributor Author

Grinnz commented Aug 28, 2019

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.

@pali
Copy link
Member

pali commented Aug 28, 2019

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.

@Grinnz
Copy link
Contributor Author

Grinnz commented Aug 28, 2019 •
edited

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.

@pali
Copy link
Member

pali commented Aug 28, 2019

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).

@choroba
Copy link
Contributor

choroba commented Sep 10, 2019 •
edited

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.

@pali pali closed this as completed in fd65fc1 Sep 23, 2019
@pali pali closed this as completed in #148 Sep 23, 2019
netbsd-srcmastr pushed a commit to NetBSD/pkgsrc that referenced this issue Apr 2, 2024
Update to 1.23
e16c510 
Upstream changes:
1.23 2023-09-10
 - Add a missing break
   (perl5-dbi/DBD-MariaDB#163)
 - Signal error if mariadb_db_async_result() fails
   (perl5-dbi/DBD-MariaDB#162)
 - Update links to project website, issues and years
 - Fix compilation with some MariaDB client library 10.2 and 10.3 versions
 - Fix mariadb_use_result attribute
   (perl5-dbi/DBD-MariaDB#173)
 - Fix statements with multiple result sets in asynchronous mode
 - Fix mariadb_sockfd attribute for Windows
 - Croaks when changing AutoCommit attribute fails
   (perl5-dbi/dbi#104)
 - Various documentation and tests fixes
 - Fix support for MariaDB Connector/C prior to 3.1.3 version
 - Fix usage of Win32::GetShortPathName() in Makefile.PL
 - Build release tarball in TAR format (instead of PAX)
 - Allow to query and change mariadb_multi_statements attribute
 - Add connect option mariadb_auth_plugin for specifying auth plugin
 - Fix support for MySQL 8.0+ client library
   (perl5-dbi/DBD-MariaDB#191)
   (perl5-dbi/DBD-mysql#329)
 - Add Github Actions CI and Cirrus CI (FreeBSD) for automated testing

1.22 2022-04-22
 - Disable usage of libmysqld.a from MySQL 8.x series
 - Install README.pod into DBD/MariaDB/ subdirectory
   (perl5-dbi/DBD-MariaDB#146)
 - Do not export driver private C functions
 - Fix typo in error message
 - Fix compatibility with new MariaDB client and server versions
   (perl5-dbi/DBD-MariaDB#164)
   (perl5-dbi/DBD-MariaDB#167)
   (perl5-dbi/DBD-mysql#333)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Install README.pod into DBD/MariaDB/ subdirectory pali/DBD-MariaDB
4 participants
@michal-josef-spacek @choroba @Grinnz @pali