Git commit-triggered builds for docs?

As I understand it, the docs are regenerated by a script that runs periodically (hourly)?

At one point, we’d talked about having this run on commit, so updates are reflected more quickly. Where does that stand?

1 Like

That’s right.

I remember having this conversation with @kevin not so long ago… This is still in my mind, but so far nothing has been done.
This whole build pipeline is a bit over complicated right now, and I can’t see any quick or easy way to achieve that at this time.
The main issue is we have a lot of repositories to monitor for new commits, not just one. And we are currently migrating some of them over GitLab.

This is on my todo list, close to “implement a CI pipeline for docs”.

4 Likes

Does it maybe make sense to less focus on getting new authors and more on getting support for docs-related development / setting up the pipeline? I think the latter issue is at least partly the origin of the lack of authors. You shouldn’t have to work through the to-do list alone. Unfortunately, I have no experience in setting up CI/CD, but maybe we could ask in the devel mailing list if someone is interested in supporting in this respect? Or at least open a thread in here that makes aware of the need.

Currently, our communication to the world outside docs makes only clear that we seek authors.

Yeah, I think that’s a big concern. Shortening the build cycle to, say, 30 minutes might be a better short term solution (depending on how long the build process actually takes). It’s unlikely to happen often, but I worry about a case where several repos have commits in relatively short order and we end up just doing builds over and over. And depending on how things queue, the time-to-publish might actually end up being longer.

I’d be really surprised if that’s the case. The biggest obstacles, at least from people I’ve talked to, have been Antora/Asciidoc and git (more the latter than the former).

I was referring to the complexities in general. I absolutely agree with your point. But even if one has experience with git (I am not sure if the issue is generally about git or how the docs use and organize git), it is still confusing (and resource intensive) to identify the applicable repo, using the scripts in the given environment that is necessary (e.g., when creating new pages), how to use the tools in interaction with each other, or who has to talk to whom when making a change (an issue in another thread) and so on. The issues are exponents to each other. Therefore, if some automation/pipeline is applied, it will at least decrease the complexity: it can do much that also makes the docs’ git environment more comprehensible and easier.

But anyway, all the above is not really relevant to the point I wanted to make: As far as I read @darknao 's comment, the to do list is currently too long for one person. Therefore, it wouldn’t hurt to check if someone with experience in related tasks is interested in supporting. It can only improve the situation.

I do not want to start a discussion about that or so, but I am a bit curious: is there a reason why the Fedora docs don’t use the “practically standardized” and widely known ReadTheDocs or some approach like that?

One of the techniques I use for decomposing processes like this so that it’s easier to grok is Metrics Based Process Mapping.

Effectively, you map a process by actor and then for each step in the process you take some measurements (estimates are fine if you’re lite on data). From there, it becomes much easier to prioritize what portion of the process to focus on improving.

Depending on how complex the process you’re mapping, it can take an hour to several hours spread over the course of a few days to complete the map. However, the benefit is that you’ll have a visual representation of the process as a whole, who is responsible for each step, who executes each step, and how long each step actually takes, among other things.

It’s just an idea. If nobody on the team is comfortable facilitating a Metrics Based Process Mapping exercise, I do them as part of my day job with Red Hat customers and assuming calendars align, would be willing to facilitate.