[Qgis-developer] 3.0 Documentation and branching

[DelazJ]

Hi Alexandre,

2017-02-07 18:18 GMT+01:00 Alexandre Neto <senhor.neto at gmail.com>:

> In my opinion, we need to take action to make sure that a developer that
> is working on a master version feature is not prevented from documenting it
> because the documentation team is still working on the 2.16 version issues.
> Example:
>
> https://github.com/qgis/QGIS-Documentation/commit/4e15534664
> 1d17a532755f535ff363b355327c91
>
> Documentation needs all the help it can get. If we expect core developer
> to help with documentation, the only time this is remotely possible is when
> they are making changes to QGIS master. For that reason, QGIS Documentation
> and QGIS master branches must be in sync regarding the version.
>
> First of all, sorry if ever i offended someone with my request in the
linked commit although, after proofreading the PR and its comments, I fail
to get the link with your real concerns in this mail.

I guess we all agree that the documentation needs help from everyone. And
none of us, I think, hesitate to remind this need and invite people to
contribute whenever possible. I also agree that core developers are somehow
the best interlocutors to help documenting features they develop so, when
they are available to help, they are more than welcome.

BUT I'm sorry, IMHO you took the wrong example (if ever there's one) to
show that someone is not welcome.

Nowhere in the discussion you pointed I can see a barrier to any
contribution from core dev. What was asked is to do like most of us: make a
pull request that can be reviewed and discussed by interested people. This
way, we avoid breaking silently documentation build (not only the
application repo is concerned, you know that - it has already occured) and
ensure a contribution free of typo or mistake. I'm sure there's no need to
replay a recent discussion on psc-list about contributing "large chunks" of
code without any review. I mistakenly(?) thought (and was proud) that the
option taken to proceed through PRs submission (for not obvious fixes) to
QGIS repo was already in the DNA of QGIS-DOC contributors.

This was on the form, and on the substance I have some concerns about the
commit itself: eg, do we need to remove any mention of Taudem, including
instructions on configuring its provider when linked to QGIS?
Btw here's a perfect example of a core dev contribution through pull
request, few days before the aboce mentioned commit and, covering the *same
issue*: https://github.com/qgis/QGIS-Documentation/pull/1670 This pull
request was being discussed. Honestly, we can't be discussing an issue, a
way to fix things and have a related commit pushed in our back, ignoring
that discussion.
In brief, there are enough things to discuss and it's worth a pull request
imo.

Any other kind of action you were thinking of to help *any contributor*
follow doc guidelines and make a great contribution?

Some time ago, we decided that we are going to release documentation for
> LTR releases. That was for us to concentrate efforts for documenting those
> special releases and, as soon it's finished, branch the repo. If we keep
> trying to complete version 2.x documentation, before we even start working
> on the 3.X version, we can end up wasting efforts in documenting things
> that have already changed in master.
>
> So, IMHO, after the release and branch a QGIS LTR version, we can delay
> the documentation branching for a while to give time for a good
> documentation release, but we can't do it for too long, to avoid the
> situation mentioned above.
>
> About branches and doc releases, I have already expressed my "slight
reluctance" on LTR-only releases (given that the next LTR is not 3.0 but
3.2 and is far away) so unless there's a real move from the team to push a
bunch of fixes to QGIS 3.0 issues, i opted to keep documenting 2.x features
(and not only 2.16) I could work on.
A recent proposal to workaround this "issue" was exposed in (another long)
message I sent few weeks ago (with few feedbacks) in the psc-list:
https://lists.osgeo.org/pipermail/qgis-psc/2017-January/005047.html


> Also, IMHO, after documentation LTR branching (e.g. 2.14), documenting any
> feature introduced in an intermediate version (e.g. 2.16, 2.18) should be
> done, if possible, taking into account changes make to it in QGIS master
> (e.g. 2.99).
>
> I might miss it but I'm not aware of any feature recently documented that
was removed in 3.0. And I agree that this is something to take into
consideration.

Kind Regards,
Harrissou

2017-02-07 18:29 GMT+01:00 Paolo Cavallini <cavallini at faunalia.it>:

> Ola Alexandre,
>
> Il 07/02/2017 18:18, Alexandre Neto ha scritto:
>
> > So, IMHO, after the release and branch a QGIS LTR version, we can delay
> > the documentation branching for a while to give time for a good
> > documentation release, but we can't do it for too long, to avoid the
> > situation mentioned above.
> >
> > Also, IMHO, after documentation LTR branching (e.g. 2.14), documenting
> > any feature introduced in an intermediate version (e.g. 2.16, 2.18)
> > should be done, if possible, taking into account changes make to it in
> > QGIS master (e.g. 2.99).
>
> seems fine to me - any objection?
> All the best, and thank you for raising the issue.
>
> --
> Paolo Cavallini - www.faunalia.eu
> QGIS & PostGIS courses: http://www.faunalia.eu/training.html
> https://www.google.com/trends/explore?date=all&geo=IT&q=qgis,arcgis
> _______________________________________________
> 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-developer/attachments/20170208/315b573f/attachment.html>