Skip to main content

Patch with custom code

Most of your SDK customization could and should be done through the Stainless config and other supported means. The SDK generator is designed to be customizable and most of your customization needs can be met through happy paths.

If you must make manual changes to an SDK, you can do so by merging code directly into main of your production (if connected, otherwise to the staging) repository as a last resort. Like other commits, you should use the Conventional Commits format for your changes so that they will show up properly in the changelog.

That's it, your changes should now be preserved. At a high level, this works by collecting and replaying your manual edits on top of the code on every new generation.

However, adding custom code patches may result in greater maintenance burden and should be done selectively. You will be indefinitely responsible for resolving any merge conflicts that arise between your manual patches and changes from the generator.

We suggest therefore:

  • trying to find an alternative - is there a Stainless config setting that will allow you to customize your SDK without using a custom code patch?
  • adding your custom code to srk/$pkg/lib & examples/ if it’s purely additive; Stainless will never modify the contents of these folders
  • minimizing the surface area of your changes - for example, if you want to remove a function from your SDK, consider removing the export instead of removing the entire function body; that way, if Stainless’ generated code changes the implementation of that function, you won’t have to handle a merge conflict

Merge conflicts​

If the generated code conflicts with your custom code, we will open a PR with a merge conflict titled NOTICE: Stainless generated code has conflicted with your custom code. You will have to resolve the conflict before more updates can land in your repo.

Resolve the merge conflict, either by:

  • resolving through Github’s UI and merging
  • checking out the head branch, running git merge {BASE_BRANCH}, pushing to the remote head branch, and merging through the UI

While resolving a conflict, you should never force push to the head branch (or any other branch). If you are having trouble resolving a conflict, feel free to contact us at support@stainlessapi.com.