feat: add algolia-migration skill for API client upgrades#26
Open
MarioAlexandruDan wants to merge 46 commits into
Open
feat: add algolia-migration skill for API client upgrades#26MarioAlexandruDan wants to merge 46 commits into
MarioAlexandruDan wants to merge 46 commits into
Conversation
Covers JS v4→v5, Python v3→v4, Go v3→v4, PHP v3→v4, Java v3→v4, C# v6→v7, Ruby v2→v3, Kotlin v2→v3, Scala v1→v2, Swift v8→v9, and Dart (new client). Includes universal breaking-change patterns, per-language reference files with primary-source code examples, 5 evals, and marketplace registration.
- dart.md: replace non-existent saveObjects with saveObject/batch pattern - go.md: fix cross-app copy (SettingsResponse→IndexSettings JSON round-trip, handle NewClient errors) - evals: add coverage for Java, C#, Kotlin, Scala, Swift, Dart (11 evals total) - README: fix trailing whitespace on instantsearch table row
…ation go.md: handle json.Marshal/Unmarshal errors in cross-app copy java.md: fix replaceAllObjects (args not ReplaceAllObjectsParams model), fix browseObjects (Iterable<T> pattern, not consumer callback) kotlin.md: searchParamsObject -> searchParams parameter name ruby.md: replace_all_objects uses positional args, not keyword scopes: evals: fix Python save_objects body= -> objects=, Java saveObjects singular/plural and waitForTasks pattern
ReplaceAllObjects, PartialUpdateObjects, and BrowseObjects all use
variadic option functions, not params structs:
- ReplaceAllObjects(indexName, objects, WithScopes([...]))
- PartialUpdateObjects(indexName, objects, WithCreateIfNotExists(false))
- BrowseObjects(indexName, BrowseParamsObject{}, WithAggregator(func(any,error)))
Also fixes BrowseObjects aggregator callback type: func(any, error) not
func(*search.BrowseResponse)
saveObjects(String, Iterable, boolean) does not exist — the 3-arg overload takes RequestOptions. Use the 4-arg form: saveObjects(indexName, objects, true, null)
… files csharp.md: - OperationIndexAsync: Operation = OperationType.Copy/Move (not string) - BrowseObjectsAsync: returns IEnumerable<T>, use foreach (not callback) - Helper changes note corrected accordingly php.md: - browseObjects returns ObjectIterator, iterate with foreach (not callback) - Wait pattern: saveObject singular for single-task wait; saveObjects with third bool arg for multi-object wait (saveObjects result is array) ruby.md: - browse_objects block receives individual hits, not page response python.md: - SearchParams import: from algoliasearch.search.models import SearchParams javascript.md: - accountCopyIndex: clarify it is on the algoliasearch meta-package client evals.json: - eval #7 C#: SaveObjectsAsync returns List<BatchResponse>; use built-in waitForTasks param instead of chaining WaitForTaskAsync on list result
go.md: remove spurious pointer dereference on TaskID (int64 not *int64) kotlin.md: browseRules/browseSynonyms helpers don't exist in v3; replace cross-app copy with confirmed browseObjects + note about rules/synonyms swift.md: browseObjects requires browseParams: + aggregator: labels (not trailing closure); add saveObjects helper with waitForTasks param
…g round python.md: transformation helpers require TransformationOptions object not transformation_region string at init javascript.md: split replaceAllRules/replaceAllSynonyms rename rows — rules use clearExistingRules:true, synonyms use replaceExistingSynonyms:true csharp.md: ChunkedBatch/IndexExists helpers have Async suffix php.md: generateSecuredApiKey is static and takes a plain array, not a typed SecuredApiKeyRestrictions model
WithChunkedBatchWaitForTasks -> WithWaitForTasks (correct ChunkedBatchOption) WithReplaceAllObjectsBatchSize -> WithBatchSize (correct option, former does not exist)
Java, PHP and C# use Iterable/IEnumerable/ObjectIterator (foreach loop), not an aggregator callback — clarify universal #6 accordingly
…erable Official docs and source confirm BrowseObjectsAsync accepts an Action<T> aggregator, not an IEnumerable<T>. Fix SKILL.md universal #6 accordingly.
… docs Rewrote every language reference file based on content fetched directly from https://www.algolia.com/doc/libraries/sdk/upgrade/<lang>.md: - Full method rename tables sourced from official docs - Correct helper signatures (ReplaceAllObjectsParams struct for Go, browseObjects iterator for PHP, aggregator callback for C#/Java/Ruby) - Cross-app copy patterns for all languages - Transformation helpers with correct init requirements - waitForApiKey, waitForAppTask documented for all languages - Complete Recommend API rename tables included Key corrections vs previous version: - Go: ReplaceAllObjects/PartialUpdateObjects/BrowseObjects use correct struct/params forms from official docs - PHP: browseObjects returns iterator (foreach), not aggregator - Ruby: browse block receives full page response (response.hits), not hits - C#: BrowseObjectsAsync confirmed aggregator (reverted IEnumerable fix) - Java: browseObjects uses aggregator callback (confirmed from docs) - Python: save_objects uses objects= param; transformation via SearchConfig - SKILL.md §6: Java moved to aggregator group
…e guides All 11 language reference files now mirror the content of the official Algolia SDK upgrade guides at algolia.com/doc/libraries/sdk/upgrade/<lang>. Includes full method rename tables, all helper changes, cross-app copy patterns, transformation helpers, and wait helpers per language. dart.md: verified against actual client source — fixed wrong package names (algolia_client_abtesting_v3, removed non-existent analytics/ingestion), waitTask/waitAppTask/waitKeyCreation method names, SearchForHits direct usage, correct enum values.
Fluf22
reviewed
May 21, 2026
Co-authored-by: Thomas Raffray <Fluf22@users.noreply.github.com>
Fluf22
reviewed
May 22, 2026
Fluf22
left a comment
Fluf22
left a comment
There was a problem hiding this comment.
A few other generic observations:
- add a trailing newline at the end of each reference file
- cleanup the doc-site rendering artifacts in reference files
- code fence decorators (icon=, theme=, highlight=, expandable)
- absolute /doc/ paths
- JSX/MDX components
It's noise for the agents, or it can even break their tool calls (no trailing newline can mess with cat, diff, etc)
Co-authored-by: Thomas Raffray <Fluf22@users.noreply.github.com>
Co-authored-by: Thomas Raffray <Fluf22@users.noreply.github.com>
Co-authored-by: Thomas Raffray <Fluf22@users.noreply.github.com>
Co-authored-by: Thomas Raffray <Fluf22@users.noreply.github.com>
Co-authored-by: Thomas Raffray <Fluf22@users.noreply.github.com>
Co-authored-by: Thomas Raffray <Fluf22@users.noreply.github.com>
- Delete references/kotlin.md (out of scope) - Delete references/dart.md (new client, no migration needed) - Remove Kotlin eval (#8) from evals.json - SKILL.md: remove Kotlin from supported migrations table, description, and browse aggregator list - marketplace.json: remove Kotlin from description
…files - Strip code fence decorators (icon=, theme=, highlight=, expandable) so language hints are bare identifiers agents can parse - Remove JSX/MDX tags (<Tip>, <Note>, </Tip>, </Note>) while preserving their content - Convert absolute /doc/ paths to plain text (broken outside algolia.com) - Add trailing newlines to all 9 reference files
…SearchConfig/client init
… correct namespaces
…prehension syntax
…Objects return type, scopes optional
…d, browse pattern accuracy, remove Kotlin/Dart from README
…val expectation; scope marketplace description
…king Dart code
- Strip doc-site rendering artifacts (code fence decorators, JSX components, /doc/ links) - Use direct enum access (OperationType.Copy, ScopeType.Rules, SynonymType.Synonym) instead of verbose .entries.first - Mark scopes optional with default in replaceAllObjects - Fix SettingsResponse → IndexSettings conversion in copyIndexBetweenApplications - Add saveObjectsWithTransformation, replaceAllObjectsWithTransformation, partialUpdateObjectsWithTransformation sections - Bring Kotlin into scope in SKILL.md, marketplace.json, and README
Fills the empty slot in the eval IDs (1–7, 9–11) and brings Kotlin to parity with the other 9 supported languages. Exercises imports, type-wrapper removal, DSL removal, initIndex removal, and the saveObjects+waitForTasks pattern.
…ides - waitForTask maxRetries default corrected to 100 in all languages - transformation helper sections aligned to the transformationOptions API: JS transformationOptions prop (transformation deprecated), Java/C# withTransformation + deprecation notes, Go TransformationOptions (not IngestionTransporter), Python transformation_options, PHP client-configuration wording - add missing WithTransformation sections for Swift and Ruby, restore Kotlin sections with the withTransformation setup - consistent 'In version X and later:' phrasing across references
…ation # Conflicts: # .claude-plugin/marketplace.json # README.md
… feat/add-algolia-migration
…ade guides Mechanical copy of doc/libraries/sdk/upgrade/*.mdx from docs-new main (includes algolia/docs-new#904) with doc-site formatting stripped: frontmatter converted to plain title/description, code-fence decorators removed, Note/Tip components flattened to indented text, internal /doc/ links flattened to plain text. Anchor and external links are kept.
Fluf22
reviewed
Jul 6, 2026
Fluf22
left a comment
Fluf22
left a comment
There was a problem hiding this comment.
Great, thanks
Let's put it reviewable so the algolia/skills team can give its opinion
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Covers JS v4→v5, Python v3→v4, Go v3→v4, PHP v3→v4, Java v3→v4, C# v6→v7, Ruby v2→v3, Kotlin v2→v3, Scala v1→v2, Swift v8→v9, and Dart (new client). Includes universal breaking-change patterns, per-language reference files with primary-source code examples, 5 evals, and marketplace registration.
What does this skill do?
Gives AI agents accurate, language-specific migration recipes so developers can upgrade Algolia backend clients to the current major version without reading long changelogs or guessing renamed methods.
Checklist
python3 scripts/validate_skills.py .passes (0 errors)evals/evals.jsonexists with at least 1 realistic prompt../other-skill/references.claude-plugin/marketplace.json(new skills only)skills/here if useful to customers; internal-only skills →algolia/internal-skills