<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">2017-03-06 13:41 GMT+01:00 Matthias Kuhn <span dir="ltr"><<a href="mailto:matthias@opengis.ch" target="_blank">matthias@opengis.ch</a>></span>:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Hello Alexandre,<br>
<br>
If I interpret your message correctly, you propose to<br>
<br>
1. Match the branch names on QGIS-Documentation with the branch names<br>
of the QGIS repository<br>
<br>
2. Only create branches for "documentation target" (read LTR) releases<br>
<br>
3. Define one of the branches as "current translation target"<br>
<br>
For now we would therefore have<br>
<br>
release-2_14 (translation target)<br>
release-2_18<br>
master (will become release-3.0 or release-3.2)<br>
<br>
Main work will be on master but backporting should be done whenever<br>
possible.<br>
Branches can be end-of-lifed as soon as LTR-period ends and branched off<br>
of master in parallel to the main QGIS repo.<br>
<br></blockquote><div>I do not understand your 1, 2, 3 points (actually I have some subtle disagreement i think :-) ) but yes, the end would be to have manual_en_2.14, manual_en_2.18 and master which will become manual_en_3.2 when released. <br></div><div>And I prefer the term of forwardporting from 2.18 to master than backporting to avoid misunderstanding about the direction of the port.<br></div><div><br> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
The advantage of this is, that new features can immediately be<br>
documented in rst (and not only md as in the issue tracker) as soon as<br>
someone wants.<br>
<br></blockquote><div>I still prefer pull requests (because PRs are a good way to avoid breakage/typos and also a kind of "what's new in QGIS?") but yes direct contribution from devs to doc will be possible.<br><br></div><div>Harrissou<br><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
If we run into major merge troubles in the worst case, text can still be<br>
copy-pasted. That's actually the same amount than it is copying text<br>
from issues.<br>
<br>
Did I forget something?<br>
<br>
I think this sounds like a very good approach, I actually can't see any<br>
downsides.<br>
<br></blockquote><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
Bests<br>
Matthias<br>
<span class="m_5325988037124260042m_1083848876456230664gmail-"><br>
On 03/06/2017 01:15 PM, Alexandre Neto wrote:<br>
> Hello all,<br>
><br>
> This will be my last arguments in this thread. After these arguments, if<br>
> I fail to make myself clear, or you guys simply disagree with my point<br>
> of view, let's just carry on with our lives. I don't want to waste<br>
> people's time (at least not documenting time :-P)<br>
><br>
</span>> Richard Duivenvoorde <<a href="mailto:rdmailings@duif.net" target="_blank">rdmailings@duif.net</a> <mailto:<a href="mailto:rdmailings@duif.net" target="_blank">rdmailings@duif.net</a>>><br>
<span class="m_5325988037124260042m_1083848876456230664gmail-">> escreveu no dia segunda, 6/03/2017 às 07:33:<br>
><br>
> On 06-03-17 00:32, Alexandre Neto wrote:<br>
> > A dom, 5/03/2017, 21:56, Richard Duivenvoorde <<a href="mailto:rdmailings@duif.net" target="_blank">rdmailings@duif.net</a><br>
> <mailto:<a href="mailto:rdmailings@duif.net" target="_blank">rdmailings@duif.net</a>><br>
</span>> > <mailto:<a href="mailto:rdmailings@duif.net" target="_blank">rdmailings@duif.net</a> <mailto:<a href="mailto:rdmailings@duif.net" target="_blank">rdmailings@duif.net</a>>>> escreveu:<br>
<div class="m_5325988037124260042m_1083848876456230664gmail-HOEnZb"><div class="m_5325988037124260042m_1083848876456230664gmail-h5">> ><br>
> > So do I understand correct that people want to write docs for<br>
> 3.0 in a<br>
> > 'fake'-3.0 branch, and the plan is then when master becomes<br>
> really 3.0<br>
> > all these changes will be cherry picked from that branch?<br>
> > Because I think that will be hard to do.... given those<br>
> branches will<br>
> > divert from each other, and it is already pretty hard to have<br>
> a good<br>
> > overview as of where to place pieces of info.<br>
> ><br>
> > Not sure if I followed your idea when you mention a "fake" 3.0 branch.<br>
> > My idea would be to have a 2.18 branch and a master branch<br>
> (effectively<br>
> > aiming at 2.99 development).<br>
> > When a documenter work in a new feature description, he would do it<br>
> > directly on master and, if that feature was already available on qgis<br>
> > 2.18, backport that description to the 2.18 branch. If it's a feature<br>
> > that will only available on 3.0, there is no backporting to do.<br>
><br>
> But... I do not understand. Currently we are writing 2.18 in master<br>
> isn't it? 2.16 is currently being translated.<br>
><br>
><br>
> Right now, master is being used to write documentation both for 2.16 and<br>
> 2.18 feaures. 2.14 is the version being translated in transifex. Right?<br>
><br>
><br>
> Next release of<br>
> documentation master will be 2.18 (as that is the next LTR according to<br>
> current QGIS release plans).<br>
><br>
> So both (undocumented) 2.16 and (new) 2.18 features can go in<br>
> documentation master now (by working away the 2.16 and 2.18 milestone<br>
> features)<br>
><br>
><br>
> So far so good. It's true. This is our current situation.<br>
><br>
><br>
> 3.0 has to wait or be documented in the issue tracker.<br>
><br>
><br>
> This is where, IMHO, it starts to fail. Having to wait for 2.18 to be<br>
> released (we have no estimate for that documentation release), or<br>
> writting it down in the bug tracker with no sure that the work will be<br>
> mergeble in the future may refrain people to documenting 3.0 new<br>
> features now (and probably won't do it later).<br>
><br>
><br>
> BUT.. but if it<br>
> is back-ported to 2.18 as you say... then it isn't a 3.0 feature anymore<br>
> is it? So can go in master now.<br>
><br>
><br>
> This would only be the case if we would have a 2.18 branch and 3.0<br>
> branch (which I was calling master).<br>
><br>
><br>
><br>
> What I mend with a '3.0 fake branch' is that if people really really do<br>
> want to write 3.0 documentation, we could do a 3.0 branch in which then<br>
> only new features available in 3.0 could come (while master hopefully<br>
> still grows and maybe splits pages with 2.18 features). When we have to<br>
> create the branch 2.18 then to start translating, and master will become<br>
> 3.0 that 'fake 3.0 branch' should be merged back in 3.0, OR 'fake 3.0'<br>
> becomes master and we have to merge all changes from old master in that<br>
> one... both a considerable amount of work I think.<br>
><br>
><br>
> My proposal would be to do this backporting continuasly, keeping the two<br>
> branches in sync as much as possible (except for 3.X features ofc). That<br>
> is, any 2.16 or 2.18 feature added to documentation, would be added<br>
> also, at the same time, to the 3.X documentation.<br>
><br>
><br>
><br>
> > But given that every new feature (which is commited with a<br>
> 'FEATURE'<br>
> > tag) has it's issue in the documentation issue tracker [0],<br>
> why not add<br>
> > information there? You can write full RST there, you can attache<br>
> > images/screendumps etc etc.<br>
> ><br>
> > If people (be it dev's or doc writers who are eager to dive<br>
> into a new<br>
> > feature) write there stuff there, it can be copied from there<br>
> into the<br>
> > rst of the docs as soon as we open up for 3.0 features.<br>
> ><br>
> > This (or having a waiting PR) is precisely what I would like to avoid,<br>
> > because if we wait for 2.18 documentation to be finished before<br>
> starting<br>
> > document 3.0, those hanging contributions can be difficult to<br>
> integrate<br>
> > later. Besides, it will be easy for other documenters to miss those<br>
> > contributions and do some overlapping.<br>
> ><br>
> > IMHO, the master branch version of documentation should (almost)<br>
> always<br>
> > match the master branch version of QGIS.<br>
><br>
> Agreed... and normally this is the case.. we should not hold back adding<br>
> features for newer versions in between LTR's. But we are in a strange<br>
> situation currently: 2 LTR's pretty soon next to each other and a lot of<br>
> work going into a future LTR while next LTR is already being developed<br>
> while not yet to be released.<br>
><br>
> Or do I just miss your point?<br>
><br>
> Who or what makes us so eager to document the 3.0 features? Going into<br>
> the issue tracker I see devs are using that (more or less) to write down<br>
> some lines or images. So do you think if they can do it somewhere else<br>
> in Github that it will be better?<br>
><br>
><br>
> If you recall, I started this thread after a contribution to Processing<br>
> Documentation by Victor Olaya, who was under the impression that QGIS<br>
> and QGIS Documentation master branches were matching (as this was the<br>
> agreement we had). Harrissou warn him that the documentation would not<br>
> fit the 2.18 release (thank you for that), because it was describing 3.0<br>
> functionalities. This lead me to think that we were facing the following<br>
> problems:<br>
><br>
> 1 - master branches of QGIS and QGIS-Documentation won't match for too<br>
> long (because of the indefinition about having a 2.18LTR release),<br>
> leading to some confusion;<br>
> 2 - There is no place for people to document features that are now<br>
> landing in QGIS master (3.0).<br>
><br>
> I know that it's not very common to have developers fully documenting<br>
> their own features, but can we agree that that would be the best<br>
> practice? Why should we (documentation team) have the burden of<br>
> revisiting the developer notes in the far future, if he is willing to<br>
> write full documentation for it right now?<br>
><br>
><br>
><br>
> And I agree, a feature should be documented as soon as possible when a<br>
> dev still has the details about an implementation... but both devs and<br>
> doc writers are free to write down as much as details in the<br>
> issue-tracker of those features:<br>
><br>
> <a href="https://github.com/qgis/QGIS-Documentation/issues?q=is%3Aopen+is%3Aissue+milestone%3A%22QGIS+3.0%22" rel="noreferrer" target="_blank">https://github.com/qgis/QGIS-<wbr>Documentation/issues?q=is%3Aop<wbr>en+is%3Aissue+milestone%3A%22Q<wbr>GIS+3.0%22</a><br>
><br>
><br>
> Isn't working your way trough the QGIS 3.0 Features issues there easier<br>
> then trying to merge/back-port two git documentation branches?<br>
><br>
><br>
> Like I said before, I'm talking about the cases where the developer (or<br>
> someone in his team/company) wants to contribute with the full<br>
> documentation of the new features, already in sphinx syntax, and ready<br>
> to be merged.<br>
><br>
> The next best thing is of course adding as much details to the new<br>
> feature issue in the tracker, and hope that any of us find the time to<br>
> digest that information and transform it in documentation.<br>
><br>
><br>
> And maybe I just miss info or your point. It is all about taking<br>
> responsibility for a decision, I personally do not dare to promise that<br>
> I would/could do the merging (and I have the feeling both Yves and<br>
> Harrisou have the same). But if you or somebody else has the feeling<br>
> he/she can handle it and promises to do so... we can do a 3.0 branch<br>
> (which I call 3.0 fake branch)<br>
><br>
><br>
> I think it would be managable if we do it continuously. Each documenter,<br>
> after merging one of his contribution, would do the backporting or<br>
> "forwardporting"to the other branch. But you are right, I can't force<br>
> others to do it if they don't want to. And if you guys don't share my<br>
> opinion that we have a problem, then it's a no go.<br>
><br>
> We could go with Yves ideas of having a backporting/forwardporting<br>
> manager, but that would consume that persons time to much.<br>
><br>
><br>
> But then make it a 3.0 branch and do not mess up master with this info.<br>
> So IF merging appears to be too much hassle we at least have current<br>
> master then to continue?<br>
><br>
><br>
> Although I would prefer the other way around, I would be ok with this<br>
> (and I agree that it's probably safer), it would not solve the "master<br>
> branches not matching (1) problem, but would solve the part of having a<br>
> place to put the 3.0 Documentation.<br>
><br>
> If we are willing to try it, I can try to assume the "forward-porting"<br>
> role for PR's that the documenters don't have time to do it.<br>
><br>
> I recall that this is a temporary situation until we release 2.18<br>
> documentation. For that reason, can we identify and focus in blockers<br>
> and missing features, and leave any enhancements for 3.0?<br>
><br>
> Kind regards,<br>
><br>
> Alexandre Neto<br>
><br>
><br>
><br>
><br>
><br>
><br>
> Or else... I just do not understand :-~<br>
><br>
> Regards,<br>
><br>
> Richard<br>
><br>
> --<br>
> Alexandre Neto<br>
> ---------------------<br>
> @AlexNetoGeo<br>
> <a href="http://sigsemgrilhetas.wordpress.com" rel="noreferrer" target="_blank">http://sigsemgrilhetas.wordpre<wbr>ss.com</a><br>
> <a href="http://gisunchained.wordpress.com" rel="noreferrer" target="_blank">http://gisunchained.wordpress.<wbr>com</a><br>
><br>
><br>
</div></div><div class="m_5325988037124260042m_1083848876456230664gmail-HOEnZb"><div class="m_5325988037124260042m_1083848876456230664gmail-h5">> ______________________________<wbr>_________________<br>
> Qgis-developer mailing list<br>
> <a href="mailto:Qgis-developer@lists.osgeo.org" target="_blank">Qgis-developer@lists.osgeo.org</a><br>
> List info: <a href="https://lists.osgeo.org/mailman/listinfo/qgis-developer" rel="noreferrer" target="_blank">https://lists.osgeo.org/mailma<wbr>n/listinfo/qgis-developer</a><br>
> Unsubscribe: <a href="https://lists.osgeo.org/mailman/listinfo/qgis-developer" rel="noreferrer" target="_blank">https://lists.osgeo.org/mailma<wbr>n/listinfo/qgis-developer</a><br>
><br>
______________________________<wbr>_________________<br>
Qgis-developer mailing list<br>
<a href="mailto:Qgis-developer@lists.osgeo.org" target="_blank">Qgis-developer@lists.osgeo.org</a><br>
List info: <a href="https://lists.osgeo.org/mailman/listinfo/qgis-developer" rel="noreferrer" target="_blank">https://lists.osgeo.org/mailma<wbr>n/listinfo/qgis-developer</a><br>
Unsubscribe: <a href="https://lists.osgeo.org/mailman/listinfo/qgis-developer" rel="noreferrer" target="_blank">https://lists.osgeo.org/mailma<wbr>n/listinfo/qgis-developer</a></div></div></blockquote></div><br></div></div>