← Back to team overview

kicad-developers team mailing list archive

Re: V6 documentation


On 1/19/22 05:18 PM, Eeli Kaikkonen wrote:
On Wed, Jan 19, 2022 at 9:13 PM Steven A. Falco <stevenfalco@xxxxxxxxx> wrote:

It would still be helpful if the doc repo could be tagged at the same point that everything else is tagged, because every single Fedora package needs a correct version in its name.  For example, it would be very strange (perhaps "illegal") to package something called the 6.0.1 doc that came from some random SHA in an untagged tree.

I don't understand why this discussion is so difficult to understand.
I agree with Jon and don't see any problem for distros. As far as I
can see the point is that the documentation package version shouldn't
be logically dependent on the KiCad packages or vice versa. You can
have package kicad-v6.0-documentation version, say, 20222001 [date],
can't you? You don't have to give it the version number 6.0.x. If a
git tag is needed for technical reasons, let's have automatic tagging
which adds a tag each day.

I don't think the discussion is difficult to understand.  But Fedora's process doesn't map into what you have just proposed.

Currently, there is one single script (a "spec" file) that controls the build of all the components of KiCad on Fedora.  This includes the executable programs, libraries, and docs.

There is nothing automatic about the process.  When a new build is needed, I download the tar files based on a tag, upload them to a lookaside cache called "dist-git", and then I queue a build on Fedora's koji system.  Once that completes, I download the resulting artifacts, test them, and then submit the artifacts for further testing by the larger community.  Eventually, those artifacts get blessed and go into the distribution system as new packages.

It is all a very manual process, and I only do it when some significant event occurs, like when a new tag is placed.  Also, it takes time - the review process generally takes a full week, so daily package updates to the docs are out of the question.

So, there is no point to tagging the docs on a daily basis.  And since that tag wouldn't agree with the one on the KiCad program, it would have to be a separately maintained thing, which would double my work.  And it would still only be built occasionally - not every day, because like I said, it is a very manual process, and takes a lot longer than a day to complete.

Personally I'd like to see things stay the way they are as far as the tagging goes.  The docs would be tagged at the same time and with the same tag as everything else.  Yes, they might soon be out of date, which is why I suggested that the code default to using the on-line copy, whenever it is available, and only use the off-line copy when there was no connection.  That would cover most users who have an internet connection.

But that is not essential.  As Jon said, if someone chooses not to install the doc package, then they'd get the on-line version.

Perhaps the best thing would be to completely eliminate building the docs on Fedora.  That way, nobody could install them, and they'd always get the on-line version.


Follow ups