[Qgis-developer] 3.0 Documentation and branching

Alexandre Neto senhor.neto at gmail.com
Mon Mar 6 04:15:00 PST 2017


Hello all,

This will be my last arguments in this thread. After these arguments, if I
fail to make myself clear, or you guys simply disagree with my point of
view, let's just carry on with our lives. I don't want to waste people's
time (at least not documenting time :-P)

Richard Duivenvoorde <rdmailings at duif.net> escreveu no dia segunda,
6/03/2017 às 07:33:

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


Right now, master is being used to write documentation both for 2.16 and
2.18 feaures. 2.14 is the version being translated in transifex. Right?


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

So far so good. It's true. This is our current situation.


> 3.0 has to wait or be documented in the issue tracker.


This is where, IMHO, it starts to fail. Having to wait for 2.18 to be
released (we have no estimate for that documentation release), or writting
it down in the bug tracker with no sure that the work will be mergeble in
the future may refrain people to documenting 3.0 new features now (and
probably won't do it later).


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

This would only be the case if we would have a 2.18 branch and 3.0 branch
(which I was calling master).


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

My proposal would be to do this backporting continuasly, keeping the two
branches in sync as much as possible (except for 3.X features ofc). That
is, any 2.16 or 2.18 feature added to documentation, would be added also,
at the same time, to the 3.X documentation.


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

If you recall, I started this thread after a contribution to Processing
Documentation by Victor Olaya, who was under the impression that QGIS and
QGIS Documentation master branches were matching (as this was the agreement
we had). Harrissou warn him that the documentation would not fit the 2.18
release (thank you for that), because it was describing 3.0
functionalities. This lead me to think that we were facing the following
problems:

1 - master branches of QGIS and QGIS-Documentation won't match for too long
(because of the indefinition about having a 2.18LTR release), leading to
some confusion;
2 - There is no place for people to document features that are now landing
in QGIS master (3.0).

I know that it's not very common to have developers fully documenting their
own features, but can we agree that that would be the best practice? Why
should we (documentation team) have the burden of revisiting the developer
notes in the far future, if he is willing to write full documentation for
it right now?


>
> 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?
>
>
Like I said before, I'm talking about the cases where the developer (or
someone in his team/company) wants to contribute with the full
documentation of the new features, already in sphinx syntax, and ready to
be merged.

The next best thing is of course adding as much details to the new feature
issue in the tracker, and hope that any of us find the time to digest that
information and transform it in documentation.


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

I think it would be managable if we do it continuously. Each documenter,
after merging one of his contribution, would do the backporting or
"forwardporting"to the other branch. But you are right, I can't force
others to do it if they don't want to. And if you guys don't share my
opinion that we have a problem, then it's a no go.

We could go with Yves ideas of having a backporting/forwardporting manager,
but that would consume that persons time to much.


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

Although I would prefer the other way around, I would be ok with this (and
I agree that it's probably safer), it would not solve the "master branches
not matching (1) problem, but would solve the part of having a place to put
the 3.0 Documentation.

If we are willing to try it, I can try to assume the "forward-porting" role
for PR's that the documenters don't have time to do it.

I recall that this is a temporary situation until we release 2.18
documentation. For that reason, can we identify and focus in blockers and
missing features, and leave any enhancements for 3.0?

Kind regards,

Alexandre Neto





>
> Or else... I just do not understand :-~
>
> Regards,
>
> Richard
>
> --
Alexandre Neto
---------------------
@AlexNetoGeo
http://sigsemgrilhetas.wordpress.com
http://gisunchained.wordpress.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-developer/attachments/20170306/0a4fbce0/attachment-0001.html>


More information about the Qgis-developer mailing list