Skip to content

Latest commit

 

History

History
98 lines (72 loc) · 4.15 KB

CONTRIBUTING.md

File metadata and controls

98 lines (72 loc) · 4.15 KB

Contributing to UI Toolkit for Jupyter

If you're reading this section, you're probably interested in contributing to UI Toolkit for Jupyter. Welcome and thanks for your interest in contributing!

Please take a look at the Contributor documentation and see the Jupyter Community Guides.

We have labeled some issues as good first issue or help wanted that we believe are good examples of small, self-contained changes. We encourage those that are new to the code base to implement and/or ask questions about these issues.

Development installation

You will need to install yarn (for example with npm install --global yarn && yarn set version berry).

To build the components packages, execute:

yarn install
yarn build

Then to interactively test or develop web components:

cd packages/components
yarn start

React components

The react components wrapper are initialized using custom-element-react-wrappers. The initialization can be reproduced by running in packages/components the script yarn run build:react. Unfortunately the initial code needs lots of changes to be usable in this case:

  • Changing the typing to inherit from React.AllHTMLAttributes - minus some event handlers that needs to be overridden.
  • Changing useImperativeHandle to expose the full HTMLElement using:
useImperativeHandle(forwardedRef, () => ref.current, [ref.current]);
  • Remove internal fast-specific properties like $presentation, styles and template.
  • The tag name, the properties and the events are extracted from the doc string of the element class definition in packages/components. You may need to add some new doc tags to get all the properties and events.

JupyterLab demo extension

To test locally the JupyterLab demo extension, using conda package manager:

conda create -n jupyter-toolkit -c conda-forge -y nodejs yarn=3 jupyterlab=4
conda activate jupyter-toolkit
yarn install
yarn build
pip install -e .
jupyter labextension develop --overwrite .

General Guidelines for Contributing

For general documentation about contributing to Jupyter projects, see the Project Jupyter Contributor Documentation and Code of Conduct.

All source code is written in TypeScript. See the Style Guide.

All source code is formatted using prettier. The benefit of using a code formatter like prettier is that it removes the topic of code style from the conversation when reviewing pull requests, thereby speeding up the review process.

You may use the prettier npm script (e.g. yarn prettier) to format the entire code base. We recommend installing a prettier extension for your code editor and configuring it to format your code with a keyboard shortcut or automatically on save.

Submitting a Pull Request Contribution

Generally, an issue should be opened describing a piece of proposed work and the issues it solves before a pull request is opened.

Issue Management

Opening an issue lets community members participate in the design discussion, makes others aware of work being done, and sets the stage for a fruitful community interaction. A pull request should reference the issue it is addressing. Once the pull request is merged, the issue related to it will also be closed. If there is additional discussion around implementation the issue may be re-opened. If additional discussion is desired, or if the pull request doesn't fully address the locked issue, please open a new issue referencing the locked issue.