Re: [QGIS-Developer] Documentation and algorithm news

[Alexandre Neto]

Hi!

It seems that I have forgotten to send my reply to the mailing list...

matteo  escreveu no dia sexta, 16/03/2018 às 08:38:

> Hi Alexandre,
>
> > Maybe I am missing something, why would lose the information? Because it
> > has not been released?
>
>
> I mean that if not documented step by step (so new algorithms or changes
> to existing ones), in a couple or releases a lot of documentation will
> be orphaned.
>
> Right now (actually after months of discussions, PRs, ecc.) we have a
> pretty stable system also for this doc section and we should try to keep
> it updated like we are trying to do with the general doc.
>

I see no reason for us to not update any new feature imediately,
independently of the QGIS version it has landed. Testing documentation is
aiming for QGIS 3.4, until then, it's just that, testing documentation.

IMHO. After QGIS 3.4, if the documentation is too behind, we can think of
branching to allow keeping documenting new features arriving in master
(3.5+).

But as you well know we are too few to maintain all the dev work.. And I
> cannot see an easy way out of this.
>
> Matteo
>

cheers,

Alex
-- 
Alexandre Neto
-
@AlexNetoGeo
http://sigsemgrilhetas.wordpress.com
http://gisunchained.wordpress.com
___
QGIS-Developer mailing list
QGIS-Developer@lists.osgeo.org
List info: https://lists.osgeo.org/mailman/listinfo/qgis-developer
Unsubscribe: https://lists.osgeo.org/mailman/listinfo/qgis-developer

Re: [QGIS-Developer] Documentation and algorithm news

[delazj]

Hi, 
Le 15 mars 2018 12:53 PM, matteo  a écrit :
>
> Hi Alexandre,
>
>
> > My suggestion is:
> > 
> > - Keep the branching as it is. That is, branch and release only for QGIS
> > 3.4 LTR
> > - Keep updating the master branch for all 3.x features (if possible giving
> > priority to 3.0 features)
> > - Backport anything missing on 2.18, if applicable.
> > - For changes (in processing or not) specific to 3.2 or 3.4 add a note
> > saying "New in QGIS 3.2" (we could use a substitution for easy tracking).
> > That way, a QGIS 3.0 user using Testing Documentation understands that the
> > feature/parameter or whatever is not yet available for him. (This is how
> > Sphinx documentation does)

This is exactly what i had in mind as a system

> > - Before the release of QGIS 3.4 Documentation, we clean up all those
> > messages.
> > 
> > IMHO, this methodology will keep the simplicity of the process, while
> > allows to document recent changes while they are still fresh.
> > 
Agreed. 

> > About the ALGCHANGE, it's a +0 for me. I would prefer to keep it as simple
> > as possible and try not to have too many tags, The processing one would
> > with the risk that Developers.
>

For information, I assigned all issues updating or creating an alg help to 
Matteo. Not all the Processing issues… yet ;) 

> always thinking aloud (really thinking aloud).. what about branching the
> docs but having a *dynamic* system based just on sphinx .. include:: ? I
> mean, branching the 3.2 release and having the correct index set up with
> just the Processing docs?
>
Fail to see the system but i'm not used to this Sphinx role. 

Regards, 
Harrissou


> Cheers
>
> Matteo
>
> ___
> QGIS-Developer mailing list
> QGIS-Developer@lists.osgeo.org
> List info: https://lists.osgeo.org/mailman/listinfo/qgis-developer
> Unsubscribe: https://lists.osgeo.org/mailman/listinfo/qgis-developer
___
QGIS-Developer mailing list
QGIS-Developer@lists.osgeo.org
List info: https://lists.osgeo.org/mailman/listinfo/qgis-developer
Unsubscribe: https://lists.osgeo.org/mailman/listinfo/qgis-developer

Re: [QGIS-Developer] Documentation and algorithm news

[matteo]

Hi Alexandre,

> I have to agree with Harrissou. Going back to branch documentation at each
> point release will not help, it will only create a bigger burden to a very
> small team of interested people, with lots of commits needing to be ported
> back or forward.
> 
> Although I have proposed to branch 3.0 documents from 2.18 before the
> release in the past, I think that was a different situation, where 2.18
> Docs were almost ready, and QGIS 3 release was yet undetermined.
> 
> I fail to see why Processing should be an exception regarding the rest of
> the documentation. Everywhere, in the document there will be parts that
> will be updated to 3.2 before the official release in QGIS 3.4 (hopefully).
> 
> Nevertheless, I am happy that someone is fully dedicated to it and I don't
> want to frustrate Matteo in his demand to keep everything updated.

no worries ;) I'm glad we are discussing about this topic

> My suggestion is:
> 
> - Keep the branching as it is. That is, branch and release only for QGIS
> 3.4 LTR
> - Keep updating the master branch for all 3.x features (if possible giving
> priority to 3.0 features)
> - Backport anything missing on 2.18, if applicable.
> - For changes (in processing or not) specific to 3.2 or 3.4 add a note
> saying "New in QGIS 3.2" (we could use a substitution for easy tracking).
> That way, a QGIS 3.0 user using Testing Documentation understands that the
> feature/parameter or whatever is not yet available for him. (This is how
> Sphinx documentation does)
> - Before the release of QGIS 3.4 Documentation, we clean up all those
> messages.
> 
> IMHO, this methodology will keep the simplicity of the process, while
> allows to document recent changes while they are still fresh.
> 
> About the ALGCHANGE, it's a +0 for me. I would prefer to keep it as simple
> as possible and try not to have too many tags, The processing one would
> with the risk that Developers.

always thinking aloud (really thinking aloud).. what about branching the
docs but having a *dynamic* system based just on sphinx .. include:: ? I
mean, branching the 3.2 release and having the correct index set up with
just the Processing docs?

Cheers

Matteo

___
QGIS-Developer mailing list
QGIS-Developer@lists.osgeo.org
List info: https://lists.osgeo.org/mailman/listinfo/qgis-developer
Unsubscribe: https://lists.osgeo.org/mailman/listinfo/qgis-developer

Re: [QGIS-Developer] Documentation and algorithm news

[Alexandre Neto]

Hello all,

I have to agree with Harrissou. Going back to branch documentation at each
point release will not help, it will only create a bigger burden to a very
small team of interested people, with lots of commits needing to be ported
back or forward.

Although I have proposed to branch 3.0 documents from 2.18 before the
release in the past, I think that was a different situation, where 2.18
Docs were almost ready, and QGIS 3 release was yet undetermined.

I fail to see why Processing should be an exception regarding the rest of
the documentation. Everywhere, in the document there will be parts that
will be updated to 3.2 before the official release in QGIS 3.4 (hopefully).

Nevertheless, I am happy that someone is fully dedicated to it and I don't
want to frustrate Matteo in his demand to keep everything updated.

My suggestion is:

- Keep the branching as it is. That is, branch and release only for QGIS
3.4 LTR
- Keep updating the master branch for all 3.x features (if possible giving
priority to 3.0 features)
- Backport anything missing on 2.18, if applicable.
- For changes (in processing or not) specific to 3.2 or 3.4 add a note
saying "New in QGIS 3.2" (we could use a substitution for easy tracking).
That way, a QGIS 3.0 user using Testing Documentation understands that the
feature/parameter or whatever is not yet available for him. (This is how
Sphinx documentation does)
- Before the release of QGIS 3.4 Documentation, we clean up all those
messages.

IMHO, this methodology will keep the simplicity of the process, while
allows to document recent changes while they are still fresh.

About the ALGCHANGE, it's a +0 for me. I would prefer to keep it as simple
as possible and try not to have too many tags, The processing one would
with the risk that Developers.

Best regards,

Alex Neto


matteo  escreveu no dia quinta, 15/03/2018 às
07:34:

> Hi Harrissou,
>
> > Does it mean that current testing becomes 3.0 and testing targets 3.2?
> > When will the doc branched? As soon as the application is released?
> > Because of the low level of man power in doc writing, we decided to have
> a LTR based release plan. Plan we struggle to follow. With the proposed
> system, we could end up with 3/4 branches (from 2.18/3.0 to 3.4) and i'm
> afraid that the only changes among them reside in some algs description.
> Because there are other areas in user manual (but also other docs in a
> branch - cookbook, training, guidelines), there will be an overhead on
> back/forward porting commits. Is syncing some alg description with the
> manual release name worth all this trouble (see below for more context
> explanation)?
>
> that is exactly the point: syncing only the Processing Help doc. As you
> well know currently Processing docs are landed (for 3.0), but for the
> current master some new algorithm is landed and some changes to existing
> algorithms have been made.
>
> > Another point related to quick releases is the "overload" of the doc
> landing page https://docs.qgis.org already crowded with some repetitive
> docs (dev or writers guidelines, GIS introduction in html and pdf +
> translations). For these docs, we can just keep a single version otherwise
> sooner we will kill our servers. See
> http://osgeo-org.1560.x6.nabble.com/Qgis-community-team-Management-of-release-independent-documents-td5318107.html
> for a discussion i fail to raise on this issue year ago.
> >
> >>> * having these branches allows doc writers to update QGIS but,
> >>> especially, Processing Help files
> >
> > Sorry. Even though i understand what you try to say, let me stress that
> there's currently room to update QGIS. There's already a lot to update in
> docs (336 issues in 3.0, 26 for 3.2). Master branch is desperately awaiting
> for writers to update QGIS. People should be aware of that.
> >
> > As i said above, i'm really afraid that it will become only a Processing
> help files branch.
> > Let's analyze the current organisation:
> > * Users (should) know that the latest released doc is 2.18 and the
> testing doc targets 3.4, hence could contain features in development.
> > * In the implemented help system, when you hit a help button in 3.0, 3.1
> (up to 3.4) it will lead you to a page in the testing manual
> >   * if the alg does not change since 3.0, all is good
> >   * if it's a 3.1 documented alg, it's also good: user will find it from
> the application. And if a 3.0 user wonders why this documented alg is not
> available to him, refer to meaning of testing doc.
> >   * if a 3.0 alg is updated (new parameters or changed behavior), here
> could be the issue. Instead of branching the whole doc, maybe we could find
> a system of tag or something like that to help readers identify the
> appropriate description? I guess this kind of system might exist (also it
> should allow to easily find concerned algs so that we regularise the
> description once the LTR is released and "a new master branched").
>
> This was also 

Re: [QGIS-Developer] Documentation and algorithm news

[matteo]

Hi Harrissou,

> Does it mean that current testing becomes 3.0 and testing targets 3.2?
> When will the doc branched? As soon as the application is released?
> Because of the low level of man power in doc writing, we decided to have a 
> LTR based release plan. Plan we struggle to follow. With the proposed system, 
> we could end up with 3/4 branches (from 2.18/3.0 to 3.4) and i'm afraid that 
> the only changes among them reside in some algs description. Because there 
> are other areas in user manual (but also other docs in a branch - cookbook, 
> training, guidelines), there will be an overhead on back/forward porting 
> commits. Is syncing some alg description with the manual release name worth 
> all this trouble (see below for more context explanation)?

that is exactly the point: syncing only the Processing Help doc. As you
well know currently Processing docs are landed (for 3.0), but for the
current master some new algorithm is landed and some changes to existing
algorithms have been made.

> Another point related to quick releases is the "overload" of the doc landing 
> page https://docs.qgis.org already crowded with some repetitive docs (dev or 
> writers guidelines, GIS introduction in html and pdf + translations). For 
> these docs, we can just keep a single version otherwise sooner we will kill 
> our servers. See 
> http://osgeo-org.1560.x6.nabble.com/Qgis-community-team-Management-of-release-independent-documents-td5318107.html
>  for a discussion i fail to raise on this issue year ago.
> 
>>> * having these branches allows doc writers to update QGIS but,
>>> especially, Processing Help files
> 
> Sorry. Even though i understand what you try to say, let me stress that 
> there's currently room to update QGIS. There's already a lot to update in 
> docs (336 issues in 3.0, 26 for 3.2). Master branch is desperately awaiting 
> for writers to update QGIS. People should be aware of that.
> 
> As i said above, i'm really afraid that it will become only a Processing help 
> files branch.
> Let's analyze the current organisation:
> * Users (should) know that the latest released doc is 2.18 and the testing 
> doc targets 3.4, hence could contain features in development. 
> * In the implemented help system, when you hit a help button in 3.0, 3.1 (up 
> to 3.4) it will lead you to a page in the testing manual
>   * if the alg does not change since 3.0, all is good
>   * if it's a 3.1 documented alg, it's also good: user will find it from the 
> application. And if a 3.0 user wonders why this documented alg is not 
> available to him, refer to meaning of testing doc.
>   * if a 3.0 alg is updated (new parameters or changed behavior), here could 
> be the issue. Instead of branching the whole doc, maybe we could find a 
> system of tag or something like that to help readers identify the appropriate 
> description? I guess this kind of system might exist (also it should allow to 
> easily find concerned algs so that we regularise the description once the LTR 
> is released and "a new master branched").

This was also the initial idea, "detach" in some way the Processing Help
files from the whole folder, what comes in my mind, just thinking aloud:

* having a separate repo (BAD IDEA! for a tons of reasons)
* make separated branches (one for each release) where we now we will
only update Processing files and only build that documentation. This
should not overload the server. Redirecting all the other doc link of
that release to the testing branch. So we will have for example:

https://docs.qgis.org/3.2/en/docs/user_manual/processing_algs/qgis/cartography.htm
that will be build and really exists

https://docs.qgis.org/3.2/en/docs/user_manual/introduction/getting_started.html

that won't be build and that will be redirected to:

https://docs.qgis.org/testing/en/docs/user_manual/introduction/getting_started.html


I think this solution needs a lot of redirecting work

*  other ideas?


>>> * if you devs change something that is linked to Processing algorithm
>>> (new algorithm OR changes to some parameter of existing algorithm) could
>>> you please add the tag "ALGCHANGE" (other name suggestions are welcome)
>>> in the commit message? This will open an issue in the doc repo with a
>>> correct label (and hopefully assign this to me)
>>>
> 
> Not sure it's either needed.
> Many months i'm cleaning the doc repo, and if there are issues i can say are 
> well tagged, it's the processing ones. 99% (to not say, ALL) of the issues 
> related to Processing have [Processing] tag in the commit title. Devs already 
> do that very well in QGIS repo so that i stopped applying the "Processing" 
> label to the generated issue report. It was a needless repetitive task.
> This to say that Processing issues are already easy to find in GitHub repo.
> 
> Now, do we need that someone points that the alg has changed (using an adhoc 
> new tag) to figure it out? If the alg is already documented and there's a new 
> issue report, 

Re: [QGIS-Developer] Documentation and algorithm news

[delazj]

Hi, 
Thanks Matteo and Richard for having brainstormed on this issue and for your 
outcome. And sorry to not have joined you.

Bear with me but i am less enthusiastic with some of the proposals for the 
reasons below


> On 03/14/2018 10:29 AM, matteo wrote:
> > Hi all,
> >
> > in the last weeks I've pointed out some problems we can have we the
> > documentation, so, together with Richard, these are the conclusions:
> >
> > * documentation repo will be branched together with QGIS release

Does it mean that current testing becomes 3.0 and testing targets 3.2?
When will the doc branched? As soon as the application is released?
Because of the low level of man power in doc writing, we decided to have a LTR 
based release plan. Plan we struggle to follow. With the proposed system, we 
could end up with 3/4 branches (from 2.18/3.0 to 3.4) and i'm afraid that the 
only changes among them reside in some algs description. Because there are 
other areas in user manual (but also other docs in a branch - cookbook, 
training, guidelines), there will be an overhead on back/forward porting 
commits. Is syncing some alg description with the manual release name worth all 
this trouble (see below for more context explanation)?

Another point related to quick releases is the "overload" of the doc landing 
page https://docs.qgis.org already crowded with some repetitive docs (dev or 
writers guidelines, GIS introduction in html and pdf + translations). For these 
docs, we can just keep a single version otherwise sooner we will kill our 
servers. See 
http://osgeo-org.1560.x6.nabble.com/Qgis-community-team-Management-of-release-independent-documents-td5318107.html
 for a discussion i fail to raise on this issue year ago.

> > * having these branches allows doc writers to update QGIS but,
> > especially, Processing Help files

Sorry. Even though i understand what you try to say, let me stress that there's 
currently room to update QGIS. There's already a lot to update in docs (336 
issues in 3.0, 26 for 3.2). Master branch is desperately awaiting for writers 
to update QGIS. People should be aware of that.

As i said above, i'm really afraid that it will become only a Processing help 
files branch.
Let's analyze the current organisation:
* Users (should) know that the latest released doc is 2.18 and the testing doc 
targets 3.4, hence could contain features in development. 
* In the implemented help system, when you hit a help button in 3.0, 3.1 (up to 
3.4) it will lead you to a page in the testing manual
  * if the alg does not change since 3.0, all is good
  * if it's a 3.1 documented alg, it's also good: user will find it from the 
application. And if a 3.0 user wonders why this documented alg is not available 
to him, refer to meaning of testing doc.
  * if a 3.0 alg is updated (new parameters or changed behavior), here could be 
the issue. Instead of branching the whole doc, maybe we could find a system of 
tag or something like that to help readers identify the appropriate 
description? I guess this kind of system might exist (also it should allow to 
easily find concerned algs so that we regularise the description once the LTR 
is released and "a new master branched").

> > * if you devs change something that is linked to Processing algorithm
> > (new algorithm OR changes to some parameter of existing algorithm) could
> > you please add the tag "ALGCHANGE" (other name suggestions are welcome)
> > in the commit message? This will open an issue in the doc repo with a
> > correct label (and hopefully assign this to me)
> >

Not sure it's either needed.
Many months i'm cleaning the doc repo, and if there are issues i can say are 
well tagged, it's the processing ones. 99% (to not say, ALL) of the issues 
related to Processing have [Processing] tag in the commit title. Devs already 
do that very well in QGIS repo so that i stopped applying the "Processing" 
label to the generated issue report. It was a needless repetitive task.
This to say that Processing issues are already easy to find in GitHub repo.

Now, do we need that someone points that the alg has changed (using an adhoc 
new tag) to figure it out? If the alg is already documented and there's a new 
issue report, then something has changed.

That said, it's not contradictory with a well described alg commit as suggested 
by Matthias. Thing we still miss because documenting alg help requires to check 
either the dialog or the code. 

Only the automatic assignment would not be handled by the current system unless 
we assign any processing-mentioned issue to you. 
> >
> > With this system we will have (at least) the chance to have Processing
> > Help updated and not loosing all the work done till now.
> >

Something that annoys me (and to be honest frustrates me a lot) in the recent 
discussions i read is my feeling that docs status/quality/interest is all about 
Processing help update. Don't get me wrong: i'm glad we covered those 
descriptions and we deliver algs with 

Re: [QGIS-Developer] Documentation and algorithm news

[Matthias Kuhn]

Thanks Matteo and Richard,

This sounds like a very good path forward. Having up-to-date
documentation in this area is crucial and this approach with branching
and tagging sounds like a very good workflow to me.

This mainly depends now on developers to provide enough context and
proper tagging of the commit message.

I guess you'd expect it something like this as pull request text (which
will be merged and not rebased, so we have the triggers fire properly)


Add a new parameter for [x]

This allows to highly customize the behavior and control the awesomeness
of this algorithm fine-grained and precise.

Here follow pictures of results with [x] set to 100 and 1000.

[ALGCHANGE]


Thanks a lot for the good work, it is much appreciated

Matthias


On 03/14/2018 10:29 AM, matteo wrote:
> Hi all,
>
> in the last weeks I've pointed out some problems we can have we the
> documentation, so, together with Richard, these are the conclusions:
>
> * documentation repo will be branched together with QGIS release
> * having these branches allows doc writers to update QGIS but,
> especially, Processing Help files
> * if you devs change something that is linked to Processing algorithm
> (new algorithm OR changes to some parameter of existing algorithm) could
> you please add the tag "ALGCHANGE" (other name suggestions are welcome)
> in the commit message? This will open an issue in the doc repo with a
> correct label (and hopefully assign this to me)
>
>
> With this system we will have (at least) the chance to have Processing
> Help updated and not loosing all the work done till now.
>
> Feedbacks are more than welcome
>
> Cheers and thanks to Richard for all the inputs!
>
> Matteo
> ___
> QGIS-Developer mailing list
> QGIS-Developer@lists.osgeo.org
> List info: https://lists.osgeo.org/mailman/listinfo/qgis-developer
> Unsubscribe: https://lists.osgeo.org/mailman/listinfo/qgis-developer
>

___
QGIS-Developer mailing list
QGIS-Developer@lists.osgeo.org
List info: https://lists.osgeo.org/mailman/listinfo/qgis-developer
Unsubscribe: https://lists.osgeo.org/mailman/listinfo/qgis-developer

[QGIS-Developer] Documentation and algorithm news

[matteo]

Hi all,

in the last weeks I've pointed out some problems we can have we the
documentation, so, together with Richard, these are the conclusions:

* documentation repo will be branched together with QGIS release
* having these branches allows doc writers to update QGIS but,
especially, Processing Help files
* if you devs change something that is linked to Processing algorithm
(new algorithm OR changes to some parameter of existing algorithm) could
you please add the tag "ALGCHANGE" (other name suggestions are welcome)
in the commit message? This will open an issue in the doc repo with a
correct label (and hopefully assign this to me)


With this system we will have (at least) the chance to have Processing
Help updated and not loosing all the work done till now.

Feedbacks are more than welcome

Cheers and thanks to Richard for all the inputs!

Matteo
___
QGIS-Developer mailing list
QGIS-Developer@lists.osgeo.org
List info: https://lists.osgeo.org/mailman/listinfo/qgis-developer
Unsubscribe: https://lists.osgeo.org/mailman/listinfo/qgis-developer