Too much deprecated functions documentation to mantain

[cvvergara]

During the v2.x series, the deprecated functions documentation has being keep around "for reference". For example the deprecated function like pgr_getColumnName that has no replacement and that was deprecated on 2.1: The function has to be kept for backwards compatability. But does that mean that the link to the documentation has to be made if its deprecated and no longer mantained? I think keeping the documentation of the function encourages people to keep using it.

Change wrapper (That use the replacement when there is one) Update news Update change Log Add to deprecated.rst the deprecated one(s) Add to Proposed functions the new signature(s) Modify the documented results given by the new algorithms on the old documentation Update links. etc Make sure they don't show up in the index

So basically I want to get rid of the following section(s) on the documentation:

http://docs.pgrouting.org/2.4/en/doc/index.html#discontinued-deprecated-functions http://docs.pgrouting.org/2.4/en/doc/src/developer/discontinued.html#discontinued http://docs.pgrouting.org/2.4/en/doc/deprecated.html

Together with the documentation of the deprecated functions.

Task I think would be:

• [x] make a wiki on how to upgrade from one version to another
  • [x] the functions for "developers" on version 2.0.x are not supposed to be used by a pgRouting user on the first place, they are no longer maintained.
  • [x] Document the functions that have conflicts on parameters types
• [x] delete the deprecated documentation

[robe2]

I think you should get rid of deprecated functions. People have enough trouble keeping track of what they should be using without having to worry about what they should not be using.

If it's not documented, don't use it, should be the motto.

[cvvergara]

Made a demo of a Migration guide, for example, imagine that pgr_bdAstar is rewritten on 2.5 Then the migration guide would look like: https://github.com/cvvergara/pgrouting/wiki/Migration-Guide

[woodbri]

This looks very good. Nice job!

[dkastl]

What about having some sort of "Landing Page", which could be https://github.com/cvvergara/pgrouting/wiki/Migration-Guide On this page would be a table of contents with links to Wiki Pages like the one mentioned, for example:

• Migrating from 2.5 to 3.0
• Migrating from 2.4 to 2.5
• ...

The advantage of this approach would be, that a) the Migration Wiki page doesn't get too long with new releases, and b) we can keep the link the same.

[dkastl]

If you think it looks "too empty", the Migration Guide page could contain some general advice like how to make a data backup before upgrading.

[cvvergara]

I was thinking more on: Only one migration page, with an index at the top for fast navigation and the most resent migration at the top. The migrations are accumulative. The link I posted is in my fork just for a demo, (style, contents) The landing page shall be in the main repo wiki

[cvvergara]

@dkastl advantage of being in a wiki .... We can add any advise that we see fit

[dkastl]

Yes, Wiki sounds good for that purpose. I'm usually in favor or shorter linked pages and couldn't find a way to automatically generated a table of content for example. But I'm not strongly against a single page either. I just thought it's easier to maintain and to find information in it.

[cvvergara]

with an "good" index at the top will be fine, I'll start making it, we can then evaluate how it "grows" and see if breaking it into different pages is needed.

[cvvergara]

@dkastl Can you have a look? (it has an index) https://github.com/pgRouting/pgrouting/wiki/Migration-Guide

[cvvergara]

Simplified a lot the documentation by removing the documentatio of deprecated functions