<div dir="ltr">I agree this should not go in the User Guide, and should be versioned with the code.<div><br></div><div>How about putting it in a DEVELOPING.md file (as was previously suggested I think?).</div><div><br></div><div>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.</div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Tue, Dec 12, 2023 at 4:56 PM Regina Obe <<a href="mailto:lr@pcorp.us">lr@pcorp.us</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">I have this ticket open <br>
<br>
<a href="https://trac.osgeo.org/postgis/ticket/5638" rel="noreferrer" target="_blank">https://trac.osgeo.org/postgis/ticket/5638</a><br>
<br>
Which I'd like to discuss.<br>
<br>
Our machinery is getting smarter and our tests are getting better.<br>
Like now our machinery tests how views that use functions are impacted.<br>
<br>
We have new special comment syntax that will automatically rename old<br>
functions and drop them if they are not in use during an upgrade<br>
<br>
By putting in a comment such as<br>
<br>
-- Replaces st_clip(raster, integer[], geometry, float8[], boolean)<br>
deprecated in 3.5.0<br>
<br>
As I did here<br>
<br>
<a href="https://trac.osgeo.org/postgis/ticket/5638" rel="noreferrer" target="_blank">https://trac.osgeo.org/postgis/ticket/5638</a><br>
<br>
But all this is by PostGIS convention, which even we as core developers<br>
don't know about often.<br>
<br>
So the question is where do we put this useful information about how to<br>
<br>
1) Define a new function<br>
2) Define documentation for new function<br>
3) Replace a function<br>
4) When it is okay or not okay to drop a function or rename arg names and<br>
what's the best way to do it<br>
<br>
We already have this file -<br>
<a href="https://git.osgeo.org/gitea/postgis/postgis/src/branch/master/STYLE" rel="noreferrer" target="_blank">https://git.osgeo.org/gitea/postgis/postgis/src/branch/master/STYLE</a> which<br>
suggests it's just for style guidance which it mostly is except<br>
I don't think we bother with astyle anymore and just use .editorconfig now.<br>
<br>
I'm thinking we scrap STYLE (and incorporate it in or reference it in<br>
CONTRIBUTING,md) and augment the CONTRIBUTING.md file (sections for the<br>
above items)<br>
It should live with the rest of the code base, cause our machinery gets<br>
smarter with each new major release.<br>
For example I don't think this Replaces commenting lives in any other branch<br>
except master -- Sandro correct me if I misspoke.<br>
<br>
We could put in the user documentation, but I feel that's not a place where<br>
developers look for how to contribute, though I could be mistaken.<br>
<br>
Anyone have thoughts on where this should live?<br>
<br>
Thanks,<br>
Regina<br>
<br>
</blockquote></div>