README.md

Fedora Packaging Committee

Welcome! This is the Pagure instance for the Fedora Packaging Committee.

The Pagure repository is used to store the source of Packaging Guidelines, track related issues and accept changes via pull requests.

For more information on the committee and its processes, see the page in the main Fedora wiki here.

You can view the actual packaging guidelines here.

Packaging Guideline Development

Checking the Effect of Your Changes

To quickly check whether the changes you have made to a .adoc file cause the desired changes to the HTML code, use Asciidoctor. It is in the package rubygem-asciidoctor, and is, despite the package name, usable from a command prompt:

$ asciidoctor path/to/file.adoc

This will generate an HTML file corresponding to the input file. The style will differ but the HTML code as such is supposed to match what will end up on the website, allowing you to see whether the Asciidoc code works as you intended.

Quick Preview in the Browser

You can install the Asciidoctor browser extension from https://github.com/asciidoctor/asciidoctor-browser-extension to get a quick browser preview. As with running asciidoctor directly, the results won't look exactly like the final result will, but it's reasonable for checking the formatting.

This will also work to preview files from within Pagure, which is handy for checking the results of pull requests without pulling and locally generating the documents. Simply navigate to a file and click the Raw button.

Note that under Firefox, the extension will not run on file:// URLs unless you press enter on the URL bar.

Building the Whole Set of Guidelines

For building the whole set of guidelines locally and viewing them in the same style as on the website, there is a container-based build procedure. This will download and execute container blobs containing Antora, and produce a complete set of HTML documents and stylesheets, which can then be browsed through a temporary HTTP server.

Prerequisites:

  • make
  • podman
  • python3

Run the following commands and open http://localhost:8000/

$ make
$ make serve

Note that running make may require root on releases earlier than Fedora 29.

Writing

Antora is used for managing the various documents which comprise the guidelines and integrating them into the rest of Fedora Documentation.

The guidelines themselves are written in AsciiDoc. Some useful information about AsciiDoc can be found below:

Conventions and Preferences

The Packaging Committee tries to follow the following, and it is preferred that pull requests do the same.

  • Use Semantic Line Breaks to make diffing simpler.
  • Prefer https://example.com[here] over link:https://example.com[here]
  • Prefer [#some-ref] over [[some-ref]]