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?
  • For purely additive helper or utility code, consider adding it to the package's lib directory. Or use examples to show how to use the your SDK. Stainless will never modify the contents of these directories. The exact location of the lib directory is language dependent. For example, in a Node.js SDK, it would be src/lib, while in Python it would be in src/$package_name/lib.
  • 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 by following the instructions in the PR body.

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.

Managing repository state​

In general, Stainless manages your SDK's repo for you entirely, and we only support a limited number of user-driven operations:

  • merging in your release PRs
  • patching the main branch of your repository with custom code
  • resolving a custom code merge conflict PR (by following the instructions in the PR body)

If you would like to view all of the custom code that you have added to an SDK, click the link to the gist in the SDK Studio. You can also remove all the custom code that you've added by clicking on the trash can icon next to the link.

You should never modify the generated branch of your repository, and you should never force push to any branch. If your repo ends up in an unexpected state, please contact support@stainlessapi.com rather than attempting to fix manually.