kicad-doc-devs team mailing list archive

[Jon Evans <jon@xxxxxxxxxxxxx>]

I don't have an opinion on banning translation of master, if people want to
translate it that seems fine!
It's more like translation of master is less urgent, so I don't want anyone
to see it as a burden.

Regarding where to start the branch, why not start it off of the tip of
master, then go back and remove things that are not relevant to 5.1?
That would keep the translation improvements but require a few fixup
commits.

If we base the branch off of an older tag or commit, we might lose out on
some work that should go in to the 5.1.x docs.

-Jon

On Thu, May 7, 2020 at 4:40 PM Nick Østergaard <oe.nick@xxxxxxxxx> wrote:

> Hello
>
> I guess I am the one primarily against branching, reasoned in the fact
> that there are things on master, even small things that are not
> getting fixed. Having master ban translations could demotivate some,
> but I think it is better as it is way easier to break translations and
> demotivate translators that way. I am ok with us trying the branch
> approach again, now that we have tried it without -- hopefully it will
> be better, but only time will tell. Please prove that it will be
> better.
>
> Clearly, Jon mentions he would like to maintain master and implicitly
> set himself in the (not yet existing) CODEOWNERS file. :) That would
> be awesome.
>
> Who is going to maintain 5.1?
>
> So I suggest we go with suggesting translators not to spend time on
> master, as also mentioned in the notes on
>
> https://gitlab.com/kicad/services/kicad-doc/-/blob/master/docs-versioning.adoc#user-content-branch-relations-working-rules-for-document
>
> Should we ban translation updates on master completely? If so we
> should probably update the CI to inform people if they accidentally
> submit translated stuff for master.
>
> Specifically, probably only that one section should stay and the
> others are slightly wrong should be removed. This can be put in the
> README for better visibility.
>
> In reality, I have been open for a 5.1 branch for a long time, but no
> one have shown interest in actually using that as an excuse to even
> maintain master. See https://github.com/KiCad/kicad-doc/issues/719
>
> Jon, you can decide if we want to branch from 5.1.2 or
> 814321ecf474f2c1a6061a01122c9b3148b17a2e. I have pushed the 5.1 branch
> I have with merge-base on the latest commit for now.
>
> Regards
> Nick Østergaard
>
> On Thu, 7 May 2020 at 19:19, Jon Evans <jon@xxxxxxxxxxxxx> wrote:
> >
> > Why not just not translate the master docs branch (if you start using
> branches)?
> > It seems OK to just keep it in English as long as the docs are in
> development alongside the code.
> > Then when the feature freeze happens the translation can start.
> >
> > -Jon
> >
> > On Thu, May 7, 2020 at 1:17 PM <f.dos.santos@xxxxxxx> wrote:
> >>
> >>
> >> 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
> >>
> >> --
> >> 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
> >
> > --
> > 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
>