https://bugzilla.redhat.com/show_bug.cgi?id=2036396
Bug ID: 2036396 Summary: Review Request: ocaml-mdx - Executable code blocks inside markdown files Product: Fedora Version: rawhide Hardware: All OS: Linux Status: NEW Component: Package Review Severity: medium Priority: medium Assignee: nobody@fedoraproject.org Reporter: loganjerry@gmail.com QA Contact: extras-qa@fedoraproject.org CC: package-review@lists.fedoraproject.org Target Milestone: --- Classification: Fedora
Spec URL: https://jjames.fedorapeople.org/ocaml-mdx/ocaml-mdx.spec SRPM URL: https://jjames.fedorapeople.org/ocaml-mdx/ocaml-mdx-2.0.0-1.fc36.src.rpm Fedora Account System Username: jjames Description: mdx enables execution of code blocks inside markdown files. There are (currently) two sub-commands, corresponding to two modes of operation: preprocessing (`ocaml-mdx pp`) and tests (`ocaml-mdx test`).
The preprocessor mode enables mixing documentation and code, and the practice of "literate programming" using markdown and OCaml.
The test mode enables ensuring that shell scripts and OCaml fragments in the documentation always stay up-to-date.
The blocks in markdown files can be parameterized by `mdx`-specific labels, that will change the way `mdx` interprets the block. The syntax is: `<!-- $MDX labels -->`, where `labels` is a list of valid labels separated by a comma. This line must immediately precede the block it is attached to.
https://bugzilla.redhat.com/show_bug.cgi?id=2036396
Jerry James loganjerry@gmail.com changed:
What |Removed |Added ---------------------------------------------------------------------------- Depends On| |2036395 Doc Type|--- |If docs needed, set a value
Referenced Bugs:
https://bugzilla.redhat.com/show_bug.cgi?id=2036395 [Bug 2036395] Review Request: ocaml-odoc-parser - Parser for OCaml documentation comments
https://bugzilla.redhat.com/show_bug.cgi?id=2036396
Christopher Crouse mail@amz-x.com changed:
What |Removed |Added ---------------------------------------------------------------------------- CC| |mail@amz-x.com
--- Comment #1 from Christopher Crouse mail@amz-x.com --- Hi James,
Maybe I can give some suggestions:
[1] I would improve the readability in the %files section, by adding in a few new lines (personal preference), for example: ...
%doc CHANGES.md README.md %license LICENSE.md
%{_bindir}/ocaml-mdx %{_bindir}/ocaml-mdx-test
%dir %{_libdir}/ocaml/%{srcname}/ %dir %{_libdir}/ocaml/%{srcname}/test/ %dir %{_libdir}/ocaml/%{srcname}/top/
%{_libdir}/ocaml/%{srcname}/META %{_libdir}/ocaml/%{srcname}/{,*/}*.cma %{_libdir}/ocaml/%{srcname}/{,*/}*.cmi
%ifarch %{ocaml_native_compiler} %{_libdir}/ocaml/%{srcname}/{,*/}*.cmxs %endif
...
[2] I would move the `%ifarch %{ocaml_native_compiler}` condition in the %files devel section of the spec to the bottom. Keeping it consistent with [1], and add a few additional new lines as well, for example:
...
%files devel
%if %{with docs} %doc _build/default/_doc/* %endif
%{_libdir}/ocaml/%{srcname}/dune-package %{_libdir}/ocaml/%{srcname}/opam %{_libdir}/ocaml/%{srcname}/{,*/}*.cmt %{_libdir}/ocaml/%{srcname}/{,*/}*.cmti %{_libdir}/ocaml/%{srcname}/{,*/}*.mli
%ifarch %{ocaml_native_compiler} %{_libdir}/ocaml/%{srcname}/{,*/}*.a %{_libdir}/ocaml/%{srcname}/{,*/}*.cmx %{_libdir}/ocaml/%{srcname}/{,*/}*.cmxa %endif
...
[3] I would recommend using rpmautospec for the package once it is imported. It will make maintaining the *Release* field and writing %changelog messages unnecessary in the future. Documented here, if you're interested: https://docs.pagure.org/fedora-infra.rpmautospec/index.html
Note: I did run a Koji scratch rawhide build, and it failed, `DEBUG util.py:444: No matching package to install: 'ocaml-odoc-parser-devel >= 0.9.0')`. It's expected since the *depends on* is correct (https://bugzilla.redhat.com/show_bug.cgi?id=2036395)
https://bugzilla.redhat.com/show_bug.cgi?id=2036396
Arthur Bols arthur@bols.dev changed:
What |Removed |Added ---------------------------------------------------------------------------- Status|NEW |POST CC| |arthur@bols.dev Assignee|nobody@fedoraproject.org |arthur@bols.dev Flags| |fedora-review+
--- Comment #2 from Arthur Bols arthur@bols.dev --- Thanks Christopher, I'll take over this review.
Jerry, please review Christopher's comments.
Package Review ==============
Legend: [x] = Pass, [!] = Fail, [-] = Not applicable, [?] = Not evaluated
Remarks: ======== - Unnecessary versioned buildrequires - ocaml >= 4.08.0 - ocaml-cmdliner-devel >= 1.0.0 - ocaml-csexp-devel >= 1.3.2 - ocaml-dune >= 2.7 - ocaml-fmt-devel >= 0.8.7 - ocaml-logs-devel >= 0.7.0 - ocaml-odoc-parser-devel >= 0.9.0 - ocaml-re-devel >= 1.7.2 - ocaml-version-devel >= 2.3.0 These are satisfied in the last 3 Fedora versions (or not available), so they should be unversioned.
===== MUST items =====
C/C++: [x]: Package does not contain kernel modules. [x]: Package contains no static executables. [x]: Package does not contain any libtool archives (.la) [x]: Rpath absent or only used for internal libs.
Generic: [x]: Package is licensed with an open-source compatible license and meets other legal requirements as defined in the legal section of Packaging Guidelines. [x]: License field in the package spec file matches the actual license. Note: Checking patched sources after %prep for licenses. Licenses found: "Unknown or generated", "ISC License", "*No copyright* ISC License [generated file]". 224 files have unknown license. Detailed output of licensecheck in /home/arthur/fedora-review/2036396-ocaml- mdx/licensecheck.txt [x]: License file installed when any subpackage combination is installed. [x]: %build honors applicable compiler flags or justifies otherwise. [x]: Package contains no bundled libraries without FPC exception. [x]: Changelog in prescribed format. [x]: Sources contain only permissible code or content. [-]: Package contains desktop file if it is a GUI application. [x]: Development files must be in a -devel package [x]: Package uses nothing in %doc for runtime. [x]: Package consistently uses macros (instead of hard-coded directory names). [x]: Package is named according to the Package Naming Guidelines. [x]: Package does not generate any conflict. [x]: Package obeys FHS, except libexecdir and /usr/target. [x]: If the package is a rename of another package, proper Obsoletes and Provides are present. [x]: Requires correct, justified where necessary. [x]: Spec file is legible and written in American English. [-]: Package contains systemd file(s) if in need. [x]: Useful -debuginfo package or justification otherwise. [x]: Package is not known to require an ExcludeArch tag. [x]: Large documentation must go in a -doc subpackage. Large could be size (~1MB) or number of files. Note: Documentation size is 30720 bytes in 2 files. [x]: Package complies to the Packaging Guidelines [x]: Package successfully compiles and builds into binary rpms on at least one supported primary architecture. [x]: Package installs properly. [x]: Rpmlint is run on all rpms the build produces. Note: There are rpmlint messages (see attachment). [x]: If (and only if) the source package includes the text of the license(s) in its own file, then that file, containing the text of the license(s) for the package is included in %license. [x]: Package requires other packages for directories it uses. [x]: Package must own all directories that it creates. [x]: Package does not own files or directories owned by other packages. [x]: Package uses either %{buildroot} or $RPM_BUILD_ROOT [x]: Package does not run rm -rf %{buildroot} (or $RPM_BUILD_ROOT) at the beginning of %install. [x]: Macros in Summary, %description expandable at SRPM build time. [x]: Dist tag is present. [x]: Package does not contain duplicates in %files. [x]: Permissions on files are set properly. [x]: Package must not depend on deprecated() packages. [x]: Package use %makeinstall only when make install DESTDIR=... doesn't work. [x]: Package is named using only allowed ASCII characters. [x]: Package does not use a name that already exists. [x]: Package is not relocatable. [x]: Sources used to build the package match the upstream source, as provided in the spec URL. [x]: Spec file name must match the spec package %{name}, in the format %{name}.spec. [x]: File names are valid UTF-8. [x]: Packages must not store files under /srv, /opt or /usr/local
Ocaml: [x]: This should never happen
===== SHOULD items =====
Generic: [x]: If the source package does not include license text(s) as a separate file from upstream, the packager SHOULD query upstream to include it. [x]: Final provides and requires are sane (see attachments). [?]: Package functions as described. [x]: Latest version is packaged. [x]: Package does not include license text files separate from upstream. [-]: Sources are verified with gpgverify first in %prep if upstream publishes signatures. Note: gpgverify is not used. [-]: Description and summary sections in the package spec file contains translations for supported Non-English languages, if available. [?]: Package should compile and build into binary rpms on all supported architectures.
Reviewers note: ocaml-odoc-parser is not yet in rawhide
[x]: %check is present and all tests pass. [x]: Packages should try to preserve timestamps of original installed files. [x]: Reviewer should test that the package builds in mock. [x]: Buildroot is not present [x]: Package has no %clean section with rm -rf %{buildroot} (or $RPM_BUILD_ROOT) [x]: No file requires outside of /etc, /bin, /sbin, /usr/bin, /usr/sbin. [x]: Fully versioned dependency in subpackages if applicable. [x]: Packager, Vendor, PreReq, Copyright tags should not be in spec file [x]: Sources can be downloaded from URI in Source: tag [x]: SourceX is a working URL. [x]: Spec use %global instead of %define unless justified.
===== EXTRA items =====
Generic: [x]: Rpmlint is run on debuginfo package(s). Note: There are rpmlint messages (see attachment). [x]: Rpmlint is run on all installed packages. Note: There are rpmlint messages (see attachment). [x]: Large data in /usr/share should live in a noarch subpackage if package is arched. [x]: Spec file according to URL is the same as in SRPM.
Rpmlint (manually) ------- ocaml-mdx-debuginfo.x86_64: W: unstripped-binary-or-object /usr/lib/debug/usr/bin/ocaml-mdx-2.0.0-1.fc36.x86_64.debug ocaml-mdx-debuginfo.x86_64: W: unstripped-binary-or-object /usr/lib/debug/usr/lib64/ocaml/mdx/mdx.cmxs-2.0.0-1.fc36.x86_64.debug ocaml-mdx-devel.x86_64: E: static-library-without-debuginfo /usr/lib64/ocaml/mdx/mdx.a ocaml-mdx.x86_64: E: shared-library-without-dependency-information /usr/lib64/ocaml/mdx/mdx.cmxs ocaml-mdx-debuginfo.x86_64: E: shared-library-without-dependency-information /usr/lib/debug/usr/bin/ocaml-mdx-2.0.0-1.fc36.x86_64.debug ocaml-mdx-debuginfo.x86_64: E: shared-library-without-dependency-information /usr/lib/debug/usr/lib64/ocaml/mdx/mdx.cmxs-2.0.0-1.fc36.x86_64.debug ocaml-mdx.x86_64: W: no-manual-page-for-binary ocaml-mdx ocaml-mdx.x86_64: W: no-manual-page-for-binary ocaml-mdx-test ocaml-mdx-debuginfo.x86_64: W: no-documentation ocaml-mdx-debugsource.x86_64: W: no-documentation ocaml-mdx-devel.x86_64: W: no-documentation ocaml-mdx-debuginfo.x86_64: W: dangling-relative-symlink /usr/lib/debug/.build-id/2e/04e465cfc2577fab59beb657302232842c5541 ../../../.build-id/2e/04e465cfc2577fab59beb657302232842c5541 ocaml-mdx-debuginfo.x86_64: W: dangling-relative-symlink /usr/lib/debug/.build-id/e8/36ed41b78b83c366c34d818410a1b3bb442512 ../../../.build-id/e8/36ed41b78b83c366c34d818410a1b3bb442512 ocaml-mdx.x86_64: W: binary-or-shlib-calls-gethostbyname /usr/bin/ocaml-mdx ocaml-mdx-debuginfo.x86_64: W: binary-or-shlib-calls-gethostbyname /usr/lib/debug/usr/bin/ocaml-mdx-2.0.0-1.fc36.x86_64.debug ==== 5 packages and 1 specfiles checked; 4 errors, 11 warnings, 4 badness; has taken 4.6 s ====
Looks good, package approved!
Please address the remarks above before import. If you have a good reason to keep them there, that's fine, but generally they should be removed.
https://bugzilla.redhat.com/show_bug.cgi?id=2036396
--- Comment #3 from Jerry James loganjerry@gmail.com --- Thank you for the suggestions, Christopher!
(In reply to Christopher Crouse from comment #1)
[1] I would improve the readability in the %files section, by adding in a few new lines (personal preference), for example: ...
[snip]
[2] I would move the `%ifarch %{ocaml_native_compiler}` condition in the %files devel section of the spec to the bottom. Keeping it consistent with [1], and add a few additional new lines as well, for example:
Okay, I can see how that would help with readability. The current style is a carryover from other OCaml spec files, and has been partially baked into the opam2rpm tool I occasionally work on. I will consider changing the style to improve readability as you suggest. Arthur, I guess that means that I am reconsidering the answer I just gave you in the ocaml-odoc-parser review. :-)
[3] I would recommend using rpmautospec for the package once it is imported. It will make maintaining the *Release* field and writing %changelog messages unnecessary in the future. Documented here, if you're interested: https://docs.pagure.org/fedora-infra.rpmautospec/index.html
Richard Jones has a script that rebuilds all OCaml packages whenever there is an update to the base compiler. That script does not yet handle rpmautospec correctly, so I will forgo using it for now. Once his script is updated to handle that case, I'll be happy to switch over.
https://bugzilla.redhat.com/show_bug.cgi?id=2036396
--- Comment #4 from Jerry James loganjerry@gmail.com --- Thank you for the review, Arthur!
(In reply to Arthur Bols from comment #2)
- Unnecessary versioned buildrequires
These are satisfied in the last 3 Fedora versions (or not available), so
- ocaml >= 4.08.0
- ocaml-cmdliner-devel >= 1.0.0
- ocaml-csexp-devel >= 1.3.2
- ocaml-dune >= 2.7
- ocaml-fmt-devel >= 0.8.7
- ocaml-logs-devel >= 0.7.0
- ocaml-odoc-parser-devel >= 0.9.0
- ocaml-re-devel >= 1.7.2
- ocaml-version-devel >= 2.3.0
they should be unversioned.
As I remarked in the ocaml-odoc-parser review, the versioned requires are a reflection of the opam metadata. I would like to keep them.
https://bugzilla.redhat.com/show_bug.cgi?id=2036396
--- Comment #5 from Gwyn Ciesla gwync@protonmail.com --- (fedscm-admin): The Pagure repository was created at https://src.fedoraproject.org/rpms/ocaml-mdx
https://bugzilla.redhat.com/show_bug.cgi?id=2036396 Bug 2036396 depends on bug 2036395, which changed state.
Bug 2036395 Summary: Review Request: ocaml-odoc-parser - Parser for OCaml documentation comments https://bugzilla.redhat.com/show_bug.cgi?id=2036395
What |Removed |Added ---------------------------------------------------------------------------- Status|POST |CLOSED Resolution|--- |NEXTRELEASE
https://bugzilla.redhat.com/show_bug.cgi?id=2036396
Jerry James loganjerry@gmail.com changed:
What |Removed |Added ---------------------------------------------------------------------------- Status|POST |CLOSED Resolution|--- |NEXTRELEASE Fixed In Version| |ocaml-mdx-2.0.0-1.fc36 Last Closed| |2022-01-07 18:57:08
--- Comment #6 from Jerry James loganjerry@gmail.com --- This package has been built in Rawhide. Thank you again, Christopher and Arthur.
package-review@lists.fedoraproject.org