[mapserver-dev] github and Mapserver documentation

thomas bonfort thomas.bonfort at gmail.com
Mon Nov 5 01:25:47 PST 2012

+0 for option b)
I've activated the docs issue tracker at


On Fri, Nov 2, 2012 at 10:33 AM, Havard Tveite <havard.tveite at umb.no> wrote:
> 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/
> _______________________________________________
> mapserver-dev mailing list
> mapserver-dev at lists.osgeo.org
> http://lists.osgeo.org/mailman/listinfo/mapserver-dev

More information about the mapserver-dev mailing list