[QGIS-Developer] documentation rules (was [qgis/QGIS-Enhancement-Proposals] Translation of .qgs project files (#90))

[Nyall Dawson]

On Thu, 17 Jan 2019 at 02:49, Matteo Ghetta <matteo.ghetta at faunalia.eu> wrote:
>
> Fully agreed with all the comments.
>
> What are devs thoughts? ;)

I'm +1 to the policy, BUT...

in reality this is just moving part of the workload from the
(overworked) documentation team to the (overworked) PR review team.
Instead of just reviewing the code we'll also be responsible for
ensuring that the commits have good documentation or that a
documentation PR has also been submitted. It may seem like a minor
thing, but every non-code thing we have to police results in less
stringent CODE reviews.

We used to see this with documentation and Python bindings. We (the PR
reviewers) would spend a lot of time just pushing submitters to add
code doxymentation and updating bindings (and running code styling
scripts). I (personally) would end up feel bad about picking apart
contributions based on all these other criteria, and as a result
wasn't as strict on code conventions and minor code improvements as
I'd have like to be.

Now that Travis is that "bad guy" with respect to doxymentation,
Python bindings, and code formatting, it leaves the PR review team
more space to be strict about code quality.

So again, I'm +1 to the policy, but only if it's enforced
automatically on Travis by an appropriate meta unit test.

**

I think we could do this by some rules like:
- if a commit message has [feature] or [needs-docs], then the body of
the message must contain at least 200(?) characters OR contain a link
to a PR on the documentation repo (detected via regex)
- feature commits must also contain a link to an image/video/blogpost
illustrating the feature (the test would just check to ensure that
there's at least one http(s):// link in the commit body). We can add a
specific [no-pic] tag for features which explicitly DON'T need a
picture (e.g. API feature additions, server specific features which
don't have any user-facing UI changes)

Nyall


>
> Cheers
>
> Matteo
> _______________________________________________
> 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