<html xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:m="http://schemas.microsoft.com/office/2004/12/omml" xmlns="http://www.w3.org/TR/REC-html40"><head><meta http-equiv=Content-Type content="text/html; charset=utf-8"><meta name=Generator content="Microsoft Word 15 (filtered medium)"><style><!--
/* Font Definitions */
@font-face
{font-family:"Cambria Math";
panose-1:2 4 5 3 5 4 6 3 2 4;}
@font-face
{font-family:Calibri;
panose-1:2 15 5 2 2 2 4 3 2 4;}
/* Style Definitions */
p.MsoNormal, li.MsoNormal, div.MsoNormal
{margin:0in;
font-size:11.0pt;
font-family:"Calibri",sans-serif;}
a:link, span.MsoHyperlink
{mso-style-priority:99;
color:blue;
text-decoration:underline;}
span.EmailStyle18
{mso-style-type:personal-reply;
font-family:"Calibri",sans-serif;
color:windowtext;}
.MsoChpDefault
{mso-style-type:export-only;
font-family:"Calibri",sans-serif;}
@page WordSection1
{size:8.5in 11.0in;
margin:1.0in 1.0in 1.0in 1.0in;}
div.WordSection1
{page:WordSection1;}
--></style><!--[if gte mso 9]><xml>
<o:shapedefaults v:ext="edit" spidmax="1026" />
</xml><![endif]--><!--[if gte mso 9]><xml>
<o:shapelayout v:ext="edit">
<o:idmap v:ext="edit" data="1" />
</o:shapelayout></xml><![endif]--></head><body lang=EN-US link=blue vlink=purple style='word-wrap:break-word'><div class=WordSection1><p class=MsoNormal>I like that idea.<o:p></o:p></p><p class=MsoNormal><o:p> </o:p></p><p class=MsoNormal>So we create a new file DEVELOPING.md<o:p></o:p></p><p class=MsoNormal><o:p> </o:p></p><p class=MsoNormal>and the CONTRIBUTING.md would just link to it and stay short.<o:p></o:p></p><p class=MsoNormal><o:p> </o:p></p><p class=MsoNormal>That way people with no patience at all like myself (most of the time) can look at the CONTRIBUTING.md,<o:p></o:p></p><p class=MsoNormal>Click on the link to DEVELOPING.md (and think, my gosh that DEVELOPING.md document is too long), I’ll just fumble my way through the code<o:p></o:p></p><p class=MsoNormal>and see what others are doing.<o:p></o:p></p><p class=MsoNormal><o:p> </o:p></p><p class=MsoNormal>That is not to say having a detailed DEVELOPING.md will be useless, I see it as a document to glance at to remind myself when I get stuck<o:p></o:p></p><p class=MsoNormal>or to point at a section of it when someone gets a red bar on their pull request and can’t figure out why.<o:p></o:p></p><p class=MsoNormal><o:p> </o:p></p><div style='border:none;border-left:solid blue 1.5pt;padding:0in 0in 0in 4.0pt'><div><div style='border:none;border-top:solid #E1E1E1 1.0pt;padding:3.0pt 0in 0in 0in'><p class=MsoNormal><b>From:</b> Martin Davis <mtnclimb@gmail.com> <br><b>Sent:</b> Tuesday, December 12, 2023 8:28 PM<br><b>Cc:</b> PostGIS Development Discussion <postgis-devel@lists.osgeo.org><br><b>Subject:</b> Re: We need Developer Documentation<o:p></o:p></p></div></div><p class=MsoNormal><o:p> </o:p></p><div><p class=MsoNormal>I agree this should not go in the User Guide, and should be versioned with the code.<o:p></o:p></p><div><p class=MsoNormal><o:p> </o:p></p></div><div><p class=MsoNormal>How about putting it in a DEVELOPING.md file (as was previously suggested I think?).<o:p></o:p></p></div><div><p class=MsoNormal><o:p> </o:p></p></div><div><p class=MsoNormal>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.<o:p></o:p></p></div></div><p class=MsoNormal><o:p> </o:p></p><div><div><p class=MsoNormal>On Tue, Dec 12, 2023 at 4:56 PM Regina Obe <<a href="mailto:lr@pcorp.us">lr@pcorp.us</a>> wrote:<o:p></o:p></p></div><blockquote style='border:none;border-left:solid #CCCCCC 1.0pt;padding:0in 0in 0in 6.0pt;margin-left:4.8pt;margin-right:0in'><p class=MsoNormal style='margin-bottom:12.0pt'>I have this ticket open <br><br><a href="https://trac.osgeo.org/postgis/ticket/5638" 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" 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" 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<o:p></o:p></p></blockquote></div></div></div></body></html>