Migration Guide (Google Doc)

[s-taube]

Update the Migration Guide to incorporate the v4 API changes.

Related issues:

• 3874 V4 API Documentation #4235
• 3632 Introduced clean_up_search_alerts command #3890
• Clean up Advanced Search help page #3843
• Migrate oral argument API to use Elastic Search #2680
• Migrate V3 Opinion Search API to work with ES #3918
• Develop v4 Search API endpoints for documents that use join fields in Elasticsearch. #3033
• Clean up for Opinion Search Alerts. #3632

To Do:

• Document all changes in one place
• Get any missing documentation, fields, etc. from Alberto
• Update migration guide (track changes)

Note:

• Some information needs to be tracked for internal purposes, but does not need to be in the user-facing guide. Information like that can be found in v4 api changes.

[mlissner]

Hoorah, your first issue. Love it! I just made the migration guide visible to the public as well, just to be fully transparent (and to make sure it wasn't editable by the world!).

Thanks for filing this.

[s-taube]

@albertisfu, This document is an attempt to capture all the api and webhook changes in one place before organizing and adding to the migration guide.

• Anything obvious missing? Anything look inaccurate?
• If the changes I missed are documented somewhere, you can point me there and I can make updates to this doc. And feel free to edit the doc if you like.

Thank you!!

[s-taube]

Ok, I made a bunch of updates and tagged you both in a few questions in the comments (in the google doc). Getting closer! Thanks for your time @albertisfu @mlissner

[s-taube]

@albertisfu , you suggested a few API changes to add to the doc that @mlissner you indicated users don't necessarily need. Would it be helpful to document these for internal purposes? Like, I could add a separate section (that wouldn't be shared with users) with info like "specifying the field used as a tiebreaker for each search_type." lmk if this could be useful to have in one place.

[s-taube]

@mlissner two questions for you in the doc on invalid cursor error, and list of filter changes.

@albertisfu one question for you on whether there are there any more date fields that changed to add

[albertisfu]

@albertisfu , you suggested a few API changes to add to the doc that @mlissner you indicated users don't necessarily need. Would it be helpful to document these for internal purposes? Like, I could add a separate section (that wouldn't be shared with users) with info like "specifying the field used as a tiebreaker for each search_type." lmk if this could be useful to have in one place.

Yeah, I think documenting this for internal knowledge will be helpful so we can remember why the order in the frontend differs from the API.

@albertisfu one question for you on whether there are there any more date fields that changed to add

Sure, I've provided the full list of date fields.

[s-taube]

Thanks @albertisfu and @mlissner! I believe all questions have been resolved. I'll start moving this info to the Guide on Monday.

@albertisfu I added "internal reference only" sections with the info you provided. I think I captured it all, but feel free to add and edit if needed.

[s-taube]

@mlissner @albertisfu I added all the changes to the Migration Guide. This should be close to final now.

@albertisfu I tagged you on some of the fields that I want to double-check.
@mlissner I wonder if you have thoughts on section headings. I added comments to those I'm unsure of.

Feel free to comment or edit directly. Nit-picking is encouraged! Any changes to wording, formatting, flow, etc. is helpful.

[mlissner]

Thanks Stephanie. I just spent a bunch of time on this and I think I made it better. I tried to draw out the distinction between DB APIs and Search APIs, so people can focus on each. In the shuffle, I think I dropped the changes to the webhooks, but I think we can lace those back into the appropriate search API changes sections.

I also noticed (and commented) on a few more things (yes, I'm afraid so!) that I noticed, but I think it's quite close and looking good!

[s-taube]

@mlissner I added stemming and synonyms (aka #4410) to the list of all api changes (for the sake of comprehensiveness), and to the migration guide. Look right?

[s-taube]

@albertisfu I tagged you on a few more open questions in the migration guide.

[albertisfu]

Sure! I’ve answered the questions. Let me know if anything else is required.

[s-taube]

@mlissner I believe the guide is done! Do you want to review before I mark this issue as "done?"

[mlissner]

Hoorah! Wonderful news. The next step is to move this task from you over to Alberto, so he can add it to the v4 documentation PR as HTML. I'll slide this onto his backlog and take it off yours.

[mlissner]

Safe to close this one?