Ticket #194 (closed enhancement: fixed)

Opened 22 months ago

Last modified 6 weeks ago

revision to Haskell Packaging Guidelines

Reported by: petersen Owned by: spot
Priority: minor Milestone:
Component: Guideline Draft Version:
Keywords: Cc:
Blocked By: Blocking:

Description

https://fedoraproject.org/wiki/PackagingDrafts/Haskell contains a rewrite of the Haskell Packaging Guidelines, which has been in draft form for quite a while now.

Please review it.

Change History

comment:1 follow-up: ↓ 4 Changed 21 months ago by spot

An initial review lead us to request the following:

  1. a summary of changes/diffs from https://fedoraproject.org/wiki/Packaging/Haskell
  2. some justification for the additional rpm macros (specifically, the %*description, %*package, and %*post macros.

Please provide this and we will revisit this.

comment:2 Changed 19 months ago by limb

Any updates on this in response to spot's comment? If you need more time, that's ok, but if not we'll close this out in 1 week.

Last edited 19 months ago by limb (previous) (diff)

comment:3 Changed 19 months ago by limb

  • Status changed from new to closed
  • Resolution set to wontfix

comment:4 in reply to: ↑ 1 Changed 15 months ago by petersen

Sorry for being too slow to respond to the earlier comments.

I have reworked https://fedoraproject.org/wiki/PackagingDrafts/Haskell a little more to reflect the new cabal-rpm packaging tool we are now using which replaced cabal2spec and a few other minor updates, improvements, and cleanups.

Replying to spot:

  1. a summary of changes/diffs from https://fedoraproject.org/wiki/Packaging/Haskell

The actual diff is here: https://fedoraproject.org/w/index.php?title=PackagingDrafts/Haskell&diff=321552&oldid=81838

The page has been simplified and rewritten quite a lot but here is a summary of the main changes:

  • replaced introductory sections on Haskell, GHC and Cabal with a few short summarizing sentences.
  • moved Spec File Templates to beginning (fixed/updated urls)
  • consolidated naming to new Package Naming section (no actual Naming changes)
  • new Headers section describes header definitions for %pkg_name and common_summary/description
  • added a short section added on handling of Cabal Flags and a new small section explaining Dependency Generation
  • cleaned up description of Shared and Static Libraries
  • macros list updated to those currently used in templates and explained for Bin and Lib/BinLib packages (updated link to macros.ghc source file), replacing the old long section on Packaging Libraries and Packaging Programs
  • updated Files Lists section to describe current macros that generate filelists boilerplate.
  • short section added on non-Cabal Haskell
  1. some justification for the additional rpm macros (specifically, the %*description, %*package, and %*post macros.

The %ghc_devel_package, %ghc_devel_description, %ghc_package, and %ghc_description macros replace earlier %ghc_lib_package and %ghc_binlib_package macros we used for a while, now making it possible to add fields like Requires to subpackages easily while still benefitting from not having to repeat all the same standard subpackaging boilerplate. Using them simplifies package maintenance when updating packages and makes it easy to spot differences for individual packages. I can explain them in more detail if necessary.

They are also very helpful for handling secondary arch builds where there are no Haskell shared libraries available and hence no ghc-<pkgname> binary library base packages. I suppose we could have dummy base library packages there but that seems kind of silly. So these macros simplify this handling automatically whether there is a base package for the arch or not, preventing having a lot of extra %if's etc in the spec file for that.

%ghc_devel_post_postun basically just covers the old Install Scripts subsection (which wrongly mentions ghc-%{pkg_name} not ghc-%{pkg_name}-devel). It could be dropped but it is a convenience and again stops boilerplate repetition across all spec files.

More details of the template changes can be found in:

which largely cover the period since the last approved revision.

The templates and macros have become a lot more stable now over time but going forward I will try to post any draft updates to the Guidelines earlier and more often to FPC. :)

Last edited 15 months ago by petersen (previous) (diff)

comment:5 Changed 15 months ago by petersen

  • Status changed from closed to reopened
  • Resolution wontfix deleted

comment:6 Changed 13 months ago by petersen

Commenting here - just to make clear that this ticket is still open!

Any suggestions for helping this move forward?

comment:7 Changed 13 months ago by spot

#action Haskell Draft Guidelines approved (+1:6, 0:0, -1:0)

We also will move copies of the templates into the Packaging namespace rather than linking to git.

comment:8 Changed 13 months ago by spot

  • Owner set to spot
  • Status changed from reopened to new

comment:9 follow-up: ↓ 11 Changed 13 months ago by spot

One minor change requirement which we caught after voting:

%ghc_devel_post_postun => needs to be broken into two macros

Each scriptlet section should have its own "header" in the spec files and then you can use a macro within that section, so you need a %ghc_devel_post and %ghc_devel_postun invoked like this:

%post
%ghc_devel_post

%postun
%ghc_devel_postun

Otherwise, you can't leverage the macro and customize those scriptlets.

Please make that change to the draft and we'll roll it live.

Last edited 13 months ago by spot (previous) (diff)

comment:10 Changed 13 months ago by spot

Upon even further discussion, there were serious concerns about how the macros operate, and several FPC members changed their votes to reject this draft as is. Toshio will be on the ticket shortly to elaborate.

This draft reverts to a "pending" state as a result. Many apologies.

comment:11 in reply to: ↑ 9 Changed 13 months ago by petersen

Replying to spot:

%ghc_devel_post_postun => needs to be broken into two macros

Each scriptlet section should have its own "header" in the spec files and then you can use a macro within that section, so you need a %ghc_devel_post and %ghc_devel_postun invoked like this:

%post
%ghc_devel_post

%postun
%ghc_devel_postun

So basically you are saying don't use %ghc_devel_post_postun but just use %ghc_pkg_recache.

Okay I suppose we can do that (but actually in the 200+ packages we have there are no examples of needing to customize the devel scripts, so %ghc_devel_post_postun actually seems to be optimal).

comment:12 Changed 13 months ago by petersen

Here is the discussion from the FPC meeting for those in suspense:

http://meetbot.fedoraproject.org/fedora-meeting-1/2013-03-27/fpc.2013-03-27-15.57.log.html#l-16

comment:13 Changed 13 months ago by petersen

The rest is fine, but I would really appreciate being allowed to keep %ghc_files for now as I tried also to explain indirectly in the above paragraph:

for handling secondary arch builds where there are no Haskell shared libraries available and hence no ghc-<pkgname> binary library base packages. I suppose we could have dummy base library packages there but that seems kind of silly. So these macros simplify this handling automatically whether there is a base package for the arch or not, preventing having a lot of extra %if's etc in the spec file for that.

since the presence of a "%files" even if empty will automatically induce rpmbuild to create a ghc-PKG base library package, it can't really be handled in the way you suggest.

comment:14 Changed 13 months ago by petersen

At the risk of preempting Toshio's comments, I went ahead and updated the new Lib and BinLib templates in git:

http://git.fedorahosted.org/cgit/haskell-sig.git/tree/packaging-templates

expanding out %ghc_devel_package, %ghc_devel_description, %ghc_devel_post_postun, and %ghc_package, %ghc_description, as you suggested.

The simple Bin package template remains unchanged since I think FPC basically approved that one. :) ;)

If this looks more acceptable then I can go head and update the draft page to reflect this cleaner more standard approach. The previous comment still holds though - I explain with an example:

if I drop %ghc_files usage then in all packages I will need to make the following change (for many .spec files):

    -%ghc_files LICENSE
    +%global base_doc_files LICENSE
    +
    +%if %{undefined ghc_without_shared}
    +%files -n ghc-%{pkg_name} -f ghc-%{pkg_name}.files
    +%doc %base_doc_files
    +%endif
    +
    +%files -n ghc-%{pkg_name}-devel -f ghc-%{pkg_name}-devel.files\
    +%if %{defined ghc_without_shared}\
    +%doc %base_doc_files
    +%endif

I think the %ghc_files boilerplate macro is much nicer and cleaner than having to doing this, resulting in better maintainability.

I also note in passing that OpenSUSE has been using my ghc-rpm-macros, cabal2spec, and now cabal-rpm for quite a while. But I don't think/hope the changes should impact them negatively but I will try to give them aheadsup about the impending changes.

comment:15 Changed 13 months ago by toshio

Well, shoot -- I submitted this after a new comment was made so it didn't save... luckily I still had the tab open...

There seem to be a few issues but they all boil down to macro usage. To some extent, macros are a blessing to packagers since they encapsulate boilerplate into a small, easy to remember name. At some point, however, macros can degrade the readability of a spec file, make it hard to modify, or require special knowledge of what the macros do in order to avoid tripping over special cases. The use of macros in the proposed guidelines crosses over into that territory as seen by FPC initially thinking the macros were okay but discovering multiple ways that the macros didn't operate as they expected upon looking deeper.

First, two general rules: macros must never include headers ("%files", "%post", "%package", etc) for two different sections. Doing so prevents packagers from modifying the first of those sections (because the section is ended when the rpm parser encounters the header for the second section).

Macros should never include "header" type values at all, certainly not macros that enter into the Guidelines. Instead, macros should be designed to work within one of these sections and the header be explicitly written into the spec file by the packager. This greatly aids in readability and prevents mistakes by packagers unfamiliar with the macros' implementations putting in duplicate sections.

With those in mind, these are the macros we spotted with issues, if you know of more, please fix them as well:

  • %ghc_devel_post_postun -- should be broken up into two macros as spot mentioned in comment:9
  • %ghc_files -- should instead create the file list and let the packager specify the %files header themselves.
  • %ghc_devel_package and %ghc_package -- let the packager specify %package and %package -n %{name}-devel themselves
  • FPC is a little worried by the use of %common_description. Descriptions are meant to be multiline with each line no more than 80 chars to format nicely on terminals. How is this handled with the %common_description macro? We haven't tested but speculate that it will need multiple escape sequences... perhaps:
%global common_description \
line1\n\
line2\n\

Could you either get rid of the common_description portion (my preference if this is going to require adding explicit \n as that's sure to be forgotten by packagers) or test what needs to be done and add a section with the proper formatting of common_description?

Other things:

  • The package sections should be brought up above the %prep step to be consistent with other Fedora guidelines.

comment:16 Changed 13 months ago by petersen

After some more discussion with Toshio on irc, we concluded that if secondary archs also have ghc-%{pkg_name} packages, the macros can be simplified and %ghc_files is no longer a hurdle.

I made further changes to the draft templates in git to reflect this:

http://git.fedorahosted.org/cgit/haskell-sig.git/tree/packaging-templates

which I think should now be more acceptable, and I agree about the readability.

No "\n"'s are needed in %common_description but I am also pondering possibly even dropping it and/or maybe more likely %common_summary.

comment:17 Changed 13 months ago by petersen

I think I will open a new ticket when the reworked revision is ready since it will be a "rebase" to the new templates, which will be closer to the current old Guidelines and this ticket was originally filed 9 months ago, but until then I will leave this ticket open.

comment:18 Changed 12 months ago by petersen

(Ignore the last comment - looking more it was pretty easy just to remove the unwanted macros from the current draft.)

Okay I think I have finished updating the templates - they now moved to:

http://git.fedorahosted.org/cgit/haskell-sig.git/tree/templates

and reworked the draft guidelines following the feedback from FPC:

https://fedoraproject.org/wiki/PackagingDrafts/Haskell

So the changes are mostly just removals but I added a few minor new details.

In the end I even dropped %common_summary, %common_description, and %ghc_devel_requires. So I think the templates should be pretty clean and readable now, and more acceptable.

comment:19 Changed 12 months ago by spot

  • Status changed from new to writeup

Haskell Draft (with templates merged into guidelines) approved : (+1:6, 0:0, -1:0)

comment:20 Changed 12 months ago by petersen

Thanks - below is the link to the meeting discussion for completeness.

http://meetbot.fedoraproject.org/fedora-meeting-1/2013-05-01/fpc.2013-05-01-16.02.log.html#l-28

comment:21 Changed 11 months ago by petersen

I made one more trivial change to the draft: just dropping %ghc_compiler from the macros.

https://fedoraproject.org/w/index.php?title=PackagingDrafts/Haskell&diff=337658&oldid=333956

comment:22 Changed 11 months ago by petersen

Anything I can do to help land this in the wiki?

Perhaps putting the templates into Draft pages?

comment:23 Changed 10 months ago by petersen

Just for the record I have now updated all the fedora haskell packages' master branches to the new packaging templates which are also implemented in cabal-rpm-0.8.0

comment:24 Changed 8 months ago by petersen

Ping? :)

comment:25 Changed 7 months ago by toshio

Written into the Guidelines and ready for announcement.

Announcement text:

After an unintentional delay, the Haskell Guideline revision approved four months ago has been officially written into the Guidelines. A profound apology to everyone who wanted to point people at the new guidelines and couldn't find them in the meantime. The updated guidelines can be read here: https://fedoraproject.org/wiki/Packaging:Haskell

comment:26 Changed 6 weeks ago by spot

  • Status changed from writeup to closed
  • Resolution set to fixed
Note: See TracTickets for help on using tickets.