[Qgis-developer] 3.0 Documentation and branching
Matthias Kuhn
matthias at opengis.ch
Mon Mar 6 04:41:08 PST 2017
Hello Alexandre,
If I interpret your message correctly, you propose to
1. Match the branch names on QGIS-Documentation with the branch names
of the QGIS repository
2. Only create branches for "documentation target" (read LTR) releases
3. Define one of the branches as "current translation target"
For now we would therefore have
release-2_14 (translation target)
release-2_18
master (will become release-3.0 or release-3.2)
Main work will be on master but backporting should be done whenever
possible.
Branches can be end-of-lifed as soon as LTR-period ends and branched off
of master in parallel to the main QGIS repo.
The advantage of this is, that new features can immediately be
documented in rst (and not only md as in the issue tracker) as soon as
someone wants.
If we run into major merge troubles in the worst case, text can still be
copy-pasted. That's actually the same amount than it is copying text
from issues.
Did I forget something?
I think this sounds like a very good approach, I actually can't see any
downsides.
Bests
Matthias
On 03/06/2017 01:15 PM, Alexandre Neto wrote:
> 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 <mailto: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>
> > <mailto: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
>
>
> _______________________________________________
> Qgis-developer mailing list
> Qgis-developer at lists.osgeo.org
> List info: https://lists.osgeo.org/mailman/listinfo/qgis-developer
> Unsubscribe: https://lists.osgeo.org/mailman/listinfo/qgis-developer
>
More information about the Qgis-developer
mailing list