How to Contribute

Contributing to NotionJS

There are many ways to contribute to the NotionJS project: logging bugs, submitting pull requests, reporting issues, and creating suggestions.

After cloning and building the repo, check out the issues list. Issues labeled help wanted are good issues to submit a PR for. Issues labeled good first issue are great candidates to pick up if you are in the code for the first time. If you are contributing significant changes, please discuss with the assignee of the issue first before starting to work on the issue.

Prerequisites

In order to download necessary tools, clone the repository, and install dependencies via npm, you need network access.

You'll need the following tools:

• Git
• Node.JS, x64, version >= 10.x, <= 12.x
• NPM, use a package manager to install.

Install and build all of the dependencies using NPM:

cd notion-js
npm install

Troubleshooting

In case of issues, try deleting the contents of ~/.node-gyp first and then run npm cache clean and then try again.

Note: For more information on how to install NPM modules globally on UNIX systems without resorting to sudo, refer to this guide.

Install and Run

If you want to understand how NotionJS works or want to debug an issue, you'll want to get the source, build it, and run an example locally.

Getting the sources

First, fork the NotionJS repository so that you can make a pull request. Then, clone your fork locally:

git clone https://github.com/<<<your-github-account>>>/notion-js.git

Occasionally you will want to merge changes in the upstream repository (the official code repo) with your fork.

cd notion-js
git checkout master
git pull https://github.com/neurosity/notion-js.git master

Manage any merge conflicts, commit them, and then push them to your fork.

Build

Go into notion-js and start the TypeScript incremental builder:

cd notion-js
npm run watch

The incremental builder will do an initial full build and will display a message that includes the phrase "Finished compilation" once the initial build is complete. The builder will then continue to run in the terminal. It will watch for file changes and compile those changes incrementally, giving you a fast, iterative coding experience.

👉 Tip! Linux users may hit a ENOSPC error when running npm run watch, to get around this follow instructions in the VSCode Common Questions.

Run

Requirements to run examples:

• Create .env file in root directory and add:
• NEUROSITY_DEVICE_ID=deviceId
• NEUROSITY_EMAIL=email
• NEUROSITY_PASSWORD=password

Browser

Builds browser examples and serves examples in the browser with ES modules.

npm run examples:browser

Go to: http://localhost:3000

Node

npm run examples:node

Linting

We use prettier for linting our sources. You can run prettier across the sources by installing the prettier VSCode plugin or by running the prettier CLI. You can also run prettier as a VS Code task by pressing CMD+P (CTRL+P on Windows) and entering Format document.

To lint the source as you make changes you can install the prettier extension.

Work Branches

Even if you have push rights on the Neurosity/notion-js repository, you should create a personal fork and create feature branches there when you need them. This keeps the main repository clean and your personal workflow cruft out of sight.

Pull Requests

To enable us to quickly review and accept your pull requests, always create one pull request per issue and link the issue in the pull request. Never merge multiple requests in one unless they have the same root cause. Be sure to follow our Coding Guidelines and keep code changes as small as possible. Avoid pure formatting changes to code that has not been modified otherwise. Pull requests should contain tests whenever possible.

Where to Contribute

Check out the full issues list for a list of all potential areas for contributions. Note that just because an issue exists in the repository does not mean we will accept a contribution to the core editor for it. There are several reasons we may not accept a pull request like:

• Performance - One of Neurosity's core values is to deliver a lightweight API, that means it should perform well in both real and perceived performance.
• User experience - Since we want to deliver a lightweight API, the UX should feel lightweight as well and not be cluttered.
• Architectural - The team and/or feature owner needs to agree with any architectural impact a change may make. Things like new extension APIs must be discussed with and agreed upon by the feature owner.

To improve the chances to get a pull request merged you should select an issue that is labelled with the help-wanted or bug labels. If the issue you want to work on is not labelled with help-wanted or bug, you can start a conversation with the issue owner asking whether an external contribution will be considered.

To avoid multiple pull requests resolving the same issue, let others know you are working on it by saying so in a comment.

Suggestions

We're also interested in your feedback for the future of NotionJS. You can submit a suggestion or feature request through the issue tracker. To make this process more effective, we're asking that these include more information to help define them more clearly.

Discussion Etiquette

In order to keep the conversation clear and transparent, please limit discussion to English and keep things on topic with the issue. Be considerate to others and try to be courteous and professional at all times.