May I suggest that we establish some kind of standards for best-practices of docs workflow using Antora and pdf creation. Since we already have documentation-contributors-guide maybe it can be a part of it, but I would say that it needs to have some kind of versioning. Also versioning should probably describe that it's aimed at Antora process because pdf workflow best practices might require completely different tooling and therefore need to have it's own versioning. I would call it revisions so that it can specifically be associated with the contributor-guidelines and can't be confused with a version of the software.

So something like this defined as header attributes:

:rev-antora: * I think in this case it's fine to have the software name
:rev-pdf:
:rev-docbook5:
:rev-epub2:

we should avoid having the name of the software but instead focus on the workflow and how we specify it. Antora in this case should be fine (it's such a central part and is a toolchain in it's self), otherwise we could call it :rev-web: - but the problem might be that in the future Antora will be able to create pdfs as well so this could become incorrect.

For example rudder docs (https://github.com/Normation/rudder-doc) uses dblatex (via docbook) for their pdf workflow and linkchecker to find broken links. Both tools are in Fedora repos, so lets say that we adopt them as well so we would have:
:rev-pdf: 0.1 for pdf production
:rev-links: 0.1 for checking the links
so if the next workflow revision (0.2) if we settle on using some other tool than linkchecker all we would have to do is change the version.
We can then use https://asciidoctor.org/docs/user-manual/#conditional-preprocessor-directives to put the correct chunks of instructions depending on the revision of the workflow concerning that part.

Necro!

Using git subtree is one approach. I used that in a previous job to maintain common files across all of our docs repos. The downside is that you have to tell people to go update things.

Another option would be to have an RPM that provides a script to run build and preview. It could have a new option that copies templates out of /usr/share/fedora-docs-template into the working directory. Publican did something like that back in the days of us using DocBook XML and it worked pretty well for that purpose.

I think I like the latter approach, but it would require more effort. It might be worth a hackfest, virtual or otherwise.

@bcotton I think the RPM template is an awesome idea, but subtrees work as a short-term fix too. I know there are many things competing for priority, but I see this as important since this affects ALL downstream docs writers. As more and more folks get used to AsciiDoc/Antora tooling and migrate their content using the existing template, correcting this problem later will be hard.

I feel like subtrees ups the technical requirements a lot. Since we mange the scripts and templates I wonder if we should just have a bit make updates on the occasion when they change. My understanding is change is a rarity. We may even be able to script this so it can run from a script in the repo at the same time as the change.

I'd rather not do subtrees, I agree with bex that it would introduce a lot of complexity. We need a centralized approach so that everyone's scripts are updated when they run git pull. Either with an RPM (any volunteers? :) or, as bex suggests, with a script that would go through all repos and push the updated scripts.

The script could get a list of all published repos and branches from the site config, and push updated scripts to each of these, I think that should be enough. Obviously that won't get these scripts to branches in people's forks, but we shouldn't be doing that anyway.

I'll volunteer to take a first pass at a strawman RPM. If I don't have anything by the end of October, feel free to yell at me.

The script could get a list of all published repos and branches from the site config, and push updated scripts to each of these, I think that should be enough.

That seems scary to me. I'm worried about blindly pushing to other repos, plus it won't help anyone who is publishing docs to places other than docs.fp.o. Is anyone doing that? Who knows? We'd have no way of knowing!

I'll volunteer to take a first pass at a strawman RPM. If I don't have anything by the end of October, feel free to yell at me.

The script could get a list of all published repos and branches from the site config, and push updated scripts to each of these, I think that should be enough.

That seems scary to me. I'm worried about blindly pushing to other repos, plus it won't help anyone who is publishing docs to places other than docs.fp.o. Is anyone doing that? Who knows? We'd have no way of knowing!

Hmm, yeah, that's a good point. (It could open PRs I suppose, but then someone would have to merge a couple dozen of them by hand...)

One benefit of having those scripts right in the repo is that anyone can just clone a repo and use them basically straight away, without installing anything else than a container runtime. That should basically work on any Linux distro and macOS making it quite accessible for contribution.

So there's probably no right answer.

Perhaps the build scripts in the repo should do a check for updates and flag that information for the user when it happens so they know why there are extra modified files in their repo. That feels clean and meets the container runtime+clone model.