[Qgis-developer] 3.0 Documentation and branching

[Richard Duivenvoorde]

On 06-03-17 00:32, Alexandre Neto wrote:
> A dom, 5/03/2017, 21:56, Richard Duivenvoorde <rdmailings at duif.net
> <mailto:rdmailings at duif.net>> escreveu:
> 
>     So do I understand correct that people want to write docs for 3.0 in a
>     'fake'-3.0 branch, and the plan is then when master becomes really 3.0
>     all these changes will be cherry picked from that branch?
>     Because I think that will be hard to do.... given those branches will
>     divert from each other, and it is already pretty hard to have a good
>     overview as of where to place pieces of info.
> 
> Not sure if I followed your idea when you mention a "fake" 3.0 branch.
> My idea would be to have a 2.18 branch and a master branch (effectively
> aiming at 2.99 development).
> When a documenter work in a new feature description, he would do it
> directly on master and, if that feature was already available on qgis
> 2.18, backport that description to the 2.18 branch. If it's a feature
> that will only available on 3.0, there is no backporting to do.

But... I do not understand. Currently we are writing 2.18 in master
isn't it? 2.16 is currently being translated. Next release of
documentation master will be 2.18 (as that is the next LTR according to
current QGIS release plans).
So both (undocumented) 2.16 and (new) 2.18 features can go in
documentation master now (by working away the 2.16 and 2.18 milestone
features)
3.0 has to wait or be documented in the issue tracker. BUT.. but if it
is back-ported to 2.18 as you say... then it isn't a 3.0 feature anymore
is it? So can go in master now.

What I mend with a '3.0 fake branch' is that if people really really do
want to write 3.0 documentation, we could do a 3.0 branch in which then
only new features available in 3.0 could come (while master hopefully
still grows and maybe splits pages with 2.18 features). When we have to
create the branch 2.18 then to start translating, and master will become
3.0 that 'fake 3.0 branch' should be merged back in 3.0, OR 'fake 3.0'
becomes master and we have to merge all changes from old master in that
one... both a considerable amount of work I think.

>     But given that every new feature (which is commited with a 'FEATURE'
>     tag) has it's issue in the documentation issue tracker [0], why not add
>     information there? You can write full RST there, you can attache
>     images/screendumps etc etc.
> 
>     If people (be it dev's or doc writers who are eager to dive into a new
>     feature) write there stuff there, it can be copied from there into the
>     rst of the docs as soon as we open up for 3.0 features.
> 
> This (or having a waiting PR) is precisely what I would like to avoid,
> because if we wait for 2.18 documentation to be finished before starting
> document 3.0, those hanging contributions can be difficult to integrate
> later. Besides, it will be easy for other documenters to miss those
> contributions and do some overlapping.
> 
> IMHO, the master branch version of documentation should (almost) always
> match the master branch version of QGIS. 

Agreed... and normally this is the case.. we should not hold back adding
features for newer versions in between LTR's. But we are in a strange
situation currently: 2 LTR's pretty soon next to each other and a lot of
work going into a future LTR while next LTR is already being developed
while not yet to be released.

Or do I just miss your point?

Who or what makes us so eager to document the 3.0 features? Going into
the issue tracker I see devs are using that (more or less) to write down
some lines or images. So do you think if they can do it somewhere else
in Github that it will be better?

And I agree, a feature should be documented as soon as possible when a
dev still has the details about an implementation... but both devs and
doc writers are free to write down as much as details in the
issue-tracker of those features:

https://github.com/qgis/QGIS-Documentation/issues?q=is%3Aopen+is%3Aissue+milestone%3A%22QGIS+3.0%22

Isn't working your way trough the QGIS 3.0 Features issues there easier
then trying to merge/back-port two git documentation branches?

And maybe I just miss info or your point. It is all about taking
responsibility for a decision, I personally do not dare to promise that
I would/could do the merging (and I have the feeling both Yves and
Harrisou have the same). But if you or somebody else has the feeling
he/she can handle it and promises to do so... we can do a 3.0 branch
(which I call 3.0 fake branch)

But then make it a 3.0 branch and do not mess up master with this info.
So IF merging appears to be too much hassle we at least have current
master then to continue?

Or else... I just do not understand :-~

Regards,

Richard