We need Developer Documentation

[Regina Obe]

I like that idea.

 

So we create a new file DEVELOPING.md

 

and the CONTRIBUTING.md would just link to it and stay short.

 

That way people with no patience at all like myself (most of the time) can look at the CONTRIBUTING.md,

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

and see what others are doing.

 

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

or to point at a section of it when someone gets a red bar on their pull request and can’t figure out why.

 

From: Martin Davis <mtnclimb at gmail.com> 
Sent: Tuesday, December 12, 2023 8:28 PM
Cc: PostGIS Development Discussion <postgis-devel at lists.osgeo.org>
Subject: Re: We need Developer Documentation

 

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 <mailto: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/48c2c5c4/attachment.htm>