kicad-doc-devs team mailing list archive

[Wayne Stambaugh <stambaughw@xxxxxxxxx>]

I'm going to put my project leader hat on and weigh in on this.  I fully
understand the frustration of using git to manage non-code text files.
Git is incredibly powerful and insanely complex which can frustrate
inexperienced users.  That being said, I am not thrilled about the
conditional build tag proposal for the following reasons.

It may be a easier solution in the short term than learning how to
branch and cherry pick with git but over the long run it will increase
the complexity and readability of the documentation source files.

There will be random cruft accumulation from long dead versions of KiCad
that will continually have to be pruned.  This increases the maintenance
overhead for documentation developers.

It will increase the documentation build complexity by requiring a build
version to always be passed by build command.  All of our automated
documentation build scripts will have to be updated and maintained for
each new version.

Given that creating a new branch and cherry picking changes from the
master branch is fairly simple as long as commits that fix the previous
version documentation are not mixed up with new feature documentation, I
think we should create a 5.1 branch from the commit where we started
adding the first new version 6 feature documentation and cherry pick any
commits that affects the 5.1 documentation or live with what we
currently have and branch at version 6.

Cheers,

Wayne


On 5/6/20 5:50 PM, f.dos.santos@xxxxxxx wrote:
> I've pushed my experimentation with conditional compilation on my repo.
> If someone wants to try (I will not make a merge request, this is only a proof of concept).
> 
> I've used eeschema doc for testing :
> - git clone https://gitlab.com/fdossantos/kicad-doc
> - cmake stuff as usual
> - build the master branch (make eeschema)
> 
> The doc are build from master branch, it only includes the development release stuff.
> 
> Now build new docs from a 'stable' branch :
> - git checkout -b release_branch
> - cmake stuff as usual
> - build this 5.1.5 inherited branch (make eeschema)
> 
> There is 3 conditional compilation in the .adoc files :
> - In the introduction on "Publication date and software version"
> - Note 4 in section 6.5.2 Connections (Wires and Labels)
> - Section 6.5.3 Connections (Buses)
> 
> Actually those last 2 items are a fix for https://gitlab.com/kicad/services/kicad-doc/-/issues/773
> 
> Finaly, update the translation (make eeschema_updatepo_all), both text versions are included in the .po files.
> 
> 
> Francisco
>