We need Developer Documentation

[Regina Obe]

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