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.
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.
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.
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.
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:
The Packaging Committee tries to follow the following, and it is preferred that pull requests do the same.
https://example.com[here]
over link:https://example.com[here]
[#some-ref]
over [[some-ref]]