guidelines/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](https://fedoraproject.org/wiki/Packaging_Committee).

You can view the actual packaging guidelines
[here](https://docs.fedoraproject.org/en-US/packaging-guidelines/).

## 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
```

### Writing

[Antora](https://antora.org/) 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](https://asciidoc.org).
Some useful information about AsciiDoc can be found below:

* [AsciiDoc Syntax Quick Reference](https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/)
* [AsciiDoc Writer's Guide](https://asciidoctor.org/docs/asciidoc-writers-guide/)

### 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](https://sembr.org/) to make diffing simpler.
* Prefer `https://example.com[here]` over `link:https://example.com[here]`
* Prefer `[#some-ref]` over `[[some-ref]]`