#743 Add link to C/C++ build flag documentation in redhat-rpm-config
Opened 6 years ago by fweimer. Modified a year ago

Guideline page needing clarification:

https://fedoraproject.org/wiki/Packaging:C_and_C%2B%2B
https://fedoraproject.org/wiki/Packaging:Guidelines#Compiler_flags
https://fedoraproject.org/wiki/Packaging:RPMMacros#Build_flags_macros_and_variables

Explanation

We now have some documentation of individual flags and how to disable hardened and annotated builds:

https://src.fedoraproject.org/rpms/redhat-rpm-config/blob/master/f/buildflags.md

(The link is stable.) It would make sense to refer to this document from the C/C++ guidelines and the compiler flags section in the general guidelines.


Metadata Update from @tibbs:
- Issue tagged with: meeting

6 years ago

This is a really nice document, thanks for taking the time to write it

Metadata Update from @mbooth:
- Issue assigned to mbooth

6 years ago

We discussed this at this weeks meeting (https://meetbot-raw.fedoraproject.org/fedora-meeting-2/2018-02-07/fpc.2018-02-07-18.01.txt):

  • x743 Add link to C/C++ build flag docs. in redhat-rpm-config
    (geppetto, 18:05:52)
  • ACTION: mboddu Will help florian get a real draft we can vote on,
    probably merging that docs. into the C/C++ page. (geppetto,
    18:20:49)

Note that RPMMacros needs updating, too.

For the record, I was working on RPMMacros last year and had ended up with https://fedoraproject.org/wiki/User:Tibbs/RPMMacros which isn't really that much different. There was also a separate ticket about fixing that page which I would have to dig up.

From: https://meetbot-raw.fedoraproject.org/fedora-meeting-1/2018-05-31/fpc.2018-05-31-16.00.txt

@mbooth should I take over this ticket?

Metadata Update from @ignatenkobrain:
- Issue untagged with: meeting
- Issue priority set to: In Committee
- Issue tagged with: committee

6 years ago

@jaruga it's often hard to come up with such changes out of thin air, so if you could open a PR (or even just comment here with "add the following paragraph in this section in this page") would go a long way :)

It looks like this was fixed years ago:
https://pagure.io/packaging-committee/c/16efbb0b4d2337b3d59e7a61c38b78cd2a3e8c1f

Should this ticket be closed?
If the link should be moved to a more prominent location, please file a PR.

Since this has recently come up, I do think it would be worth at least having a quick think about the reasons why the build flag documentation is external to the packaging guidelines and whether that should be readdressed.

Relying on my somewhat hazy memory and two minutes of analysis of the current situation, I get the following:

  • Back when this was started, things were still in the wiki and getting things modified was really difficult.
  • Making things worse, this committee wasn't always particularly responsive.
  • The documents are in markdown and not asciidoc and so would need conversion
  • There is a need to have the documents refer to specific Fedora versions, which kind of happens automatically right now.

Now the first two are rather better; we accept PRs and the simple/obvious ones generally get merged pretty quickly, which shows that we are at least paying attention. Of course if things need more work or discussion then it's going to take longer, but I don't think that applies to the documents under consideration.

Conversion from markdown to asciidoc is pretty easy so I don't see that as too much of a problem. The document isn't all that long anyway (628 lines in F38).

I do see a minor sticking point with versioning, though. Certainly it's not hard to keep multiple copies around and with careful wording you could avoid having to "fork" off a new version of the document until something actually changes that necessitates it, but we would still need to purge old versions periodically. That's not really a big deal.

So then the question comes down to "is it worth it". Right now @fweimer can just commit whatever he needs to redhat-rpm-config with no extra bureaucracy. That's conveniently the package where the build flags are actually configured, so everything gets done in one go. Any step away from that (even if it's to a separate docs repo) would necessitate extra work.

We could somehow mirror the document occasionally, but I see that as inferior in basically every respect.

So really, we should be open to this but if the maintainers of the document don't want the extra work of keeping it as part of the packaging guidelines then it shouldn't happen and we can simply continue to provide a pointer to the file.

hm ... if the docs were written in asciidoc but still part of the redhat-rpm-config package, could we somehow <include> it as an external file when the guidelines are built? we already have a few example spec files that get included verbatim, not sure if external files are supported by the tool that builds the documentation.

Obviously anything is possible but that particular bit of magic would be up to the docs team. It would bring up questions of how changes would be noticed to trigger rebuilds. And in any case, there would still be the issue that you would get the information for rawhide but not the release branches. I'm not sure it would be worth the effort if not already well-supported.

Log in to comment on this ticket.

Metadata