[mapserver-dev] github and Mapserver documentation

[Jeff McKenna]

Hello Håvard,

I would agree with your thoughts.

As in the past documentation systems, I prefer separate documentation
tickets be created.  Most long-time MapServer devs are very good at
doing this, but it is a good time now to remind everyone to do so, and
choose a related "Docs" label.

Also, I'd like to thank you personally for your recent contributions. I
know git/github is challenging, and I thank you for wading through all this.

-jeff



On 12-11-02 6:33 AM, Havard Tveite 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


-- 
Jeff McKenna
MapServer Consulting and Training Services
http://www.gatewaygeomatics.com/