Contributing to the Superhuman Pack SDK¶
👍🎉 First off, thanks for taking the time to contribute! 🎉👍
Changes to the core SDK itself can only be made by Superhuman engineers, and they must be coordinated with changes to the Superhuman products. We do however welcome contributions to the SDK documentation, which can be done without access to or knowledge of the private codebase.
Documentation changes¶
For small contributions, such fixing a typo or adding a clarifying sentence, you can directly submit a pull request to this repo. For larger changes, such as adding a new page or code sample, first make a post to the Superhuman Community with your intentions to get feedback from a Superhuman engineer. This helps ensure that you don't waste effort for a change which may not be approved.
Style guide¶
When contributing to the documentation, please ensure your changes comply with the style guide. Some elements of the style guide are enforced automatically using lint rules, but many others must be caught manually.
Environment setup¶
While some documentation changes require only a single edit, others require building or validating your changes using the scripts in this repo's Makefile. This build system is designed to work on Unix-like command lines (Linux, Mac OSX, etc) and has a lot of dependencies.
The development and release tools require Node.js ^22.22.2 || ^24.15.0 || >=26.0.0.
Use the version pinned in .nvmrc. On your own computer, install
nvm and run the following
each time you open a terminal in the packs-sdk directory:
source setup-env.sh
Dependency installation uses pnpm 10.28.2, pinned in package.json.
make bootstrap installs that version locally and uses it to install dependencies.
An easy way to get setup is to use Google Cloud Shell, an hosted command-line environment and web IDE that comes with most of the dependencies already installed. You can launch Google Cloud Shell and clone this repo using the button below:
In Google Cloud Shell, also install pipenv:
pip install --user pipenv
export PATH=$HOME/.local/bin:$PATH
You can then install the other dependencies using the Makefile using the bootstrap script:
make bootstrap
Preview documentation¶
You can preview your changes to the documentation locally by running the MkDocs preview server:
make view-docs
This will serve the documentation on localhost:8000. If you are using Google Cloud Shell, use the Web Preview icon at the top, changing the port to "8000", to view the documentation.
Changes to reference docs¶
The reference documentation (under docs/reference/sdk) is automatically generated from the TypeScript definitions. Don't edit these markdown files directly, but instead make the change to the comment in the corresponding TypeScript file. Then to rebuild the markdown files run:
make docs
Validating your changes¶
Before opening a pull request we recommend that you first do a full build of the SDK. This will ensure that none of your changes break the core functionality of the SDK.
make build
That should succeed, and any changed files that result from it (usually in the dist directory) should be added to your PR.
Additionally, you should run the lint check to ensure that all of your changes meet our style rules:
make lint
SDK changes¶
The following section includes information about how to contribute to the SDK itself, which is only done by Superhuman engineers.
Feature documentation¶
Add documentation for a feature only after it is generally available. When developing a new feature, keep the PRs focused on SDK implementation and tests. Do not add or update feature documentation under docs/ in those PRs, including generated reference pages. SDK features may be implemented and even released in the package before they are generally available to Pack developers; publishing documentation at that point advertises functionality developers cannot use.
All new SDK surface should be marked as @hidden initially, so it doesn't show up in the documentation. This annotation will later be removed when the feature is fully available. Alternatively, use @internal for SDK surface that is only ever intended to be used by Superhuman-created Packs.
Leave feature documentation to separate follow-up PRs led by DevRel, who coordinates publication with developer availability. An SDK package release alone does not establish that a feature is ready to document.
Publishing Changes Process¶
CHANGELOG.md is for developers installing and using the public SDK package. Add an entry only when a change affects functionality those developers can use, such as an available API, a bug fix, or a compatibility change. Explain what the change enables or fixes for a Pack developer and include any action they need to take; a bare symbol name or internal implementation summary is insufficient.
Do not include internal, unreleased, or hidden features, even if their implementation ships in an SDK package release. The Unreleased heading holds upcoming consumer-facing package changes; it is not a place to announce features developers cannot use. Omit small package maintenance changes and routine dependency or package version bumps. If a change has no consumer-facing effect, leave CHANGELOG.md unchanged.
Add every new CHANGELOG.md entry only under ## [Unreleased], within an appropriate Keep a Changelog category such as ### Added, ### Changed, or ### Fixed. Category headings belong inside Unreleased; standalone bullets directly beneath the release heading fail make lint-changelog. Never add new entries to a versioned release section.
Only the release process moves Unreleased entries into a dated version section, updates package.json, and publishes to NPM using make release. Run make lint-changelog before committing a changelog edit.