[mapserver-dev] github and Mapserver documentation

[Havard Tveite]

Dear developers,

There are now quite a number of issues (opened and closed)
on Mapserver github.  In my opinion, this means that
measures should be taken to simplify searching for open
issues.
As an occasional contributor to documentation I have not
gotten used to github, and have found it more cumbersome
to work with compared to the old system.
Some things that has to do with Mapserver documentation
and github:

1) Spurred by a message on the mapserver users list, some
days ago I had a look at issues on github.  I discovered
some enhancement issues that had been closed, but where
the enhancements had not been documented.

I think it is important that all Mapserver features are
documented in the official docs.  I therefore urge
developers to keep documentation in mind.

2) It is difficult to find issues that are left open due
to missing documentation.  github provides some mechanisms,
but I don't know about all of them or how to best utilise
them.

Two options (there are probably more):

a) Issues can be given documentation tags in addition to
"feature" tags, and a tag on an open issue indicates that
that something needs to be done related to that tag.
When one task is completed, the corresponding tags should
be removed, but the issue left open until all tasks have
been completed (and all tags removed).
Since this means that issue metadata will be removed, it
will make it more difficult to navigate the issues on
github.

b) Separate issues are created for documentation.
When the coding is finalised, the original issue can be
closed, and documentation issues opened for the relevant
documentation (core, mapscript, ...).
This means some more work for the developers, and also
seems kind of strange, since many would argue that coding
and documentation belongs together.

For github I prefer option b), as that will make it easier
to navigate among the issues (both open and closed ones).

3) For the benefit of searching, all new issues should get
tagged.
It would have been great if the creator of an issue also
could do the initial tagging.  As far as I know, this is not
possible if the reporter / creator does not have sufficient
github rights.
In the current situation, I think that new issues must be
tagged by a developer with sufficient rights.

4) Issues that are finalised should be closed as soon as
possible.
This is a problem when the only thing left is the
documentation, since documentation lives in a different
github "tree", and those working on documentation do not
necessarily have sufficient rights in the github mapserver
"tree" to close issues there.

Should we consider moving documentation issues to the doc
"tree" on github?


Håvard
-- 
Håvard Tveite
Department of Mathematical Sciences and Technology, UMB
Drøbakveien 31, POBox 5003, N-1432 Ås, NORWAY
Phone: +47 64965483 Fax: +47 64965401 http://www.umb.no/imt/