kicad-doc-devs team mailing list archive

[f.dos.santos@xxxxxxx]

From: "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.

I'm not frustrated, I'm used to git ;-)
I just want to ease the translator's jobs on managing both stable and 
development versions (to be honest I was expecting more reaction from
translators to this proposal).


> 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.

I agree, readability suffers and don't "look" so good as a pure .adoc file.


> 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.

I agree, this increase the burden on writers : they need to be familiar
with the process which is not obvious and feel unnatural. 


> 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.

I'm a big fan : if it's working don't touch it ;-)
I'll take a leap of faith and hope we'll find a workflow that works for
translators too.
I, personally, think that's only the stable release need to be translated,
if someone can live the cutting edge development version, he can live
without translated documentation.


> 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.

Actually I think it will be easier to start the 5.1 branch on master and
revert those commits that are specific to version 6.
History wise it reflects what's happening.

> Cheers,
>
> Wayne

Thank you


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
> 

-- 
Mailing list: https://launchpad.net/~kicad-doc-devs
Post to     : kicad-doc-devs@xxxxxxxxxxxxxxxxxxx
Unsubscribe : https://launchpad.net/~kicad-doc-devs
More help   : https://help.launchpad.net/ListHelp