Contributing to the Coda Pack SDK¶
👍🎉 First off, thanks for taking the time to contribute! 🎉👍
Changes to the core SDK itself can only be made by Coda engineers, and they must be coordinated with changes to the core Coda product. 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 Coda Community with your intentions to get feedback from a Codan. 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.
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:
The only dependency that needs to be installed manually in Google Cloud Shell is 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
To develop on your own computer, make sure you have a compatible version of node installed in your environment. The simplest way to make sure you're using a compatible version of node is to install nvm and run the following command each time you open a terminal in the packs-sdk repo:
source setup-env.sh
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 Coda engineers.
Publishing Changes Process¶
Adjustments to the CHANGELOG.md file should be marked under ### Not yet released until a release commit is made that updates package.json and CHANGELOG.md file with a new, later version, and publishes the new version to NPM using make release.
Our CHANGELOG.md follows the Keep a Changelog standards, where there is a “Unreleased” section at the top for any unreleased changes. Upon release, it is named according to a semantic versioning system and dated.