kicad-doc-devs team mailing list archive

[f.dos.santos@xxxxxxx]

Yep, starting from master and reverting only the v6 stuff is the right move.
All my commits are 5.1.5 based and, like others, only translation work.

There are only two new v6 features introduced so far :

1) the bus feature (https://gitlab.com/kicad/services/kicad-doc/-/issues/773)
2) the position relative tool (commit 2f48eb5)

Both can be easily undone by hand.
The first one is changing a note and restoring a section.
The second one is just 1 commit to revert (2 if you want also to revert the png image).

Some translations in 1) have to be "un"-updated to put back the old bus translation.

No need to change the translations for 2) the feature will not be included if it's not
in the .adoc file.

If nobody take this task, I'll do it tomorrow and make a pull request against :
- origin/if_this_is_accepted_we_officially_have_a_5.1_branch

Francisco


----- Mail original -----
From: "Jon Evans" <jon@xxxxxxxxxxxxx>
To: "Nick Østergaard" <oe.nick@xxxxxxxxx>
Cc: "f dos santos" <f.dos.santos@xxxxxxx>, kicad-doc-devs@xxxxxxxxxxxxxxxxxxx
Date: 07/05/2020 22:54:42
Subject: Re: [Kicad-doc-devs] let's be brave and fork!



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