We need Developer Documentation

[Martin Davis]

I agree this should not go in the User Guide, and should be versioned with
the code.

How about putting it in a DEVELOPING.md file (as was previously suggested I
think?).

it could go in CONTRIBUTING.md too, since that's not got too much content
right now.  But I think it would be clearer if it was in it's own document.

On Tue, Dec 12, 2023 at 4:56 PM Regina Obe <lr at pcorp.us> wrote:

> I have this ticket open
>
> https://trac.osgeo.org/postgis/ticket/5638
>
> Which I'd like to discuss.
>
> Our machinery is getting smarter and our tests are getting better.
> Like now our machinery tests how views that use functions are impacted.
>
> We have new special comment syntax that will automatically rename old
> functions and drop them if they are not in use during an upgrade
>
> By putting in a comment such as
>
> -- Replaces st_clip(raster, integer[], geometry, float8[], boolean)
> deprecated in 3.5.0
>
> As I did here
>
> https://trac.osgeo.org/postgis/ticket/5638
>
> But all this is by PostGIS convention, which even we as core developers
> don't know about often.
>
> So the question is where do we put this useful information about how to
>
> 1) Define a new function
> 2) Define documentation for new function
> 3) Replace a function
> 4) When it is okay or not okay to drop a function or rename arg names and
> what's the best way to do it
>
> We already have this file -
> https://git.osgeo.org/gitea/postgis/postgis/src/branch/master/STYLE which
> suggests it's just for style guidance which it mostly is except
> I don't think we bother with astyle anymore and just use .editorconfig now.
>
> I'm thinking we scrap STYLE (and incorporate it in or reference it in
> CONTRIBUTING,md) and augment the CONTRIBUTING.md file (sections for the
> above items)
> It should live with the rest of the code base, cause our machinery gets
> smarter with each new major release.
> For example I don't think this Replaces commenting lives in any other
> branch
> except master -- Sandro correct me if I misspoke.
>
> We could put in the user documentation, but I feel that's not a place where
> developers look for how to contribute, though I could be mistaken.
>
> Anyone have thoughts on where this should live?
>
> Thanks,
> Regina
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/postgis-devel/attachments/20231212/f99fffb4/attachment.htm>