Welcome! This is the Pagure instance for the Fedora Package Maintainer Docs.
The Pagure repository is used to store the source of Package Maintainer Docs, track related issues and accept changes via pull requests.
You can view the actual documentation here.
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:
This repository attempts to follow the following:
https://example.com[here]
over link:https://example.com[here]
[#some-ref]
over [[some-ref]]
The documentation is intended to be maintained collectively by all Fedora packagers.
Trivial changes, such as adding links or correcting typos,
can be committed directly to the main
branch.
More substantial changes should be submitted through pull requests
and be reviewed by another contributor before merging.
Due to technical issues,
the packager
group from the Fedora Account System cannot be granted access,
so there is a dedicated Pagure group package-maintainer-docs with commit access.
Membership is granted to authors of all merged pull request.
Membership can also be requested by commenting on issue #23.
In case a pull request not reviewed in reasonable time, the following actions can be taken, in given order:
This repo includes a script to build and preview the contents of this repository.
NOTE: Please note that if you reference pages from other repositories, such links will be broken in this local preview as it only builds this repository. If you want to rebuild the whole Fedora Docs site, please see the Fedora Docs build repository for instructions.
The script works on Fedora (using Podman) and macOS (using Docker).
To build, watch and preview the site, run:
$ ./docsbuilder.sh
The result will be available at http://localhost:8080 and automatically regenerated when the repo contents change.
To check for broken links,
first install linkchecker: sudo dnf install linkchecker
.
Ensure that the preview is running,
then in another terminal window run:
./check-links.sh
Fedora Workstation doesn't come with Podman preinstalled by default — so you might need to install it using the following command:
$ sudo dnf install podman
You can also build the whole Fedora Docs site locally
to see your changes in the whole context.
This is especially useful for checking if your xref
links work properly.
To do this,
you need to clone the main Fedora Docs build repository,
modify the site.yml
file to reference a repo with your changes,
and build it.
Steps:
Clone the main repository and cd into it:
$ git clone https://pagure.io/fedora-docs/docs-fp-o.git $ cd docs-fp-o
Find a reference to the repository you're changing in the site.yml
file,
and change it so it points to your change.
So for example, if I made a modification to the Modularity docs,
I would find:
... - url: https://pagure.io/fedora-docs/modularity.git branches: - master ...
And replaced it with a pointer to my fork:
... - url: https://pagure.io/forks/asamalik/fedora-docs/modularity.git branches: - master ...
I could also point to a local repository,
using HEAD
as a branch
to preview the what's changed
without the need of making a commit.
Note: I would need to move the repository under the docs-fp-o
directory,
because the builder won't see anything above.
So I would need to create a repositories
directory in docs-fp-o
and copy my repository into it.
... - url: ./repositories/modularity branches: - HEAD ...
To build the whole site,
I would run the following
in the docs-fp-o
directory.
$ ./build.sh && ./preview.sh