Skip to content

Update Documentation: First Contribution #7715

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Update Documentation: First Contribution #7715

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9927b67
Update documentation: added first open source contribution
suhananana Aug 24, 2025
2e4239d
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Aug 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
90 changes: 59 additions & 31 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,22 @@ The `jlpm` command is JupyterLab's pinned version of [yarn](https://yarnpkg.com/

**Note**: we recommend using `mamba` to speed up the creation of the environment.

### Prerequisites

Make sure you have the following installed:
- Python >= 3.8
- Node.ja >= 18(with npm >= 9)
- [mamba](https://mamba.readthedocs.io/en/latest/) (recommended for faster environment creation)
- [git](https://git-scm.com/) for version control


### Create and Activate an Environment

```bash
# create a new environment
# Create a new environment with Python + Node.js
mamba create -n notebook -c conda-forge python nodejs -y

# activate the environment
# Activate the environment
mamba activate notebook

# Install package in development mode
Expand Down Expand Up @@ -64,12 +75,22 @@ Config dir: /home/username/miniforge3/envs/notebook/etc/jupyter
Config dir: /usr/local/etc/jupyter
```

### Run jupyter Notebook

Then start Jupyter Notebook with:

```bash
jupyter notebook
```

### Watch for changes

```bash
jlpm watch
```



### Local changes in Notebook dependencies

The development installation described above fetches JavaScript dependencies from [npmjs](https://www.npmjs.com/),
Expand All @@ -79,27 +100,41 @@ been published.

[yalc](https://github.com/wclr/yalc) can help you use local JavaScript packages when building Notebook, acting as a local package repository.



- Install yalc globally in your environment:
`npm install -g yalc`


- Publish your dependency package:\
`yalc publish`, from the package root directory.\
`yalc publish` , from the package root directory.\


For instance, if you are developing on _@jupyterlab/ui-components_, this command must be executed from
_path_to_jupyterlab/packages/ui-components_.


- Depend on this local repository in Notebook:
- from the Notebook root directory:\
`yalc add your_package` : this will create a _dependencies_ entry in the main _package.json_ file.\


With the previous example, it would be `yalc add @jupyterlab/ui-components`.
- Notebook is a monorepo, so we want this dependency to be 'linked' as a resolution (for all sub-packages) instead
of a dependency.\
The easiest way is to manually move the new entry in _package.json_ from _dependencies_ to _resolutions_.


- Build Notebook with the local dependency:\
`jlpm install && jlpm build`


Changes in the dependency must then be built and pushed using `jlpm build && yalc push` (from the package root directory),
and fetched from Notebook using `yarn install`.

**Warning**: you need to make sure that the dependencies of Notebook and the local package match correctly,
otherwise there will be errors with webpack during build.\

In the previous example, both _@jupyterlab/ui-components_ and Notebook depend on _@jupyterlab/coreutils_. We
strongly advise you to depend on the same version.

Expand All @@ -114,6 +149,7 @@ jlpm run test

There are also end to end tests to cover higher level user interactions, located in the `ui-tests` folder. To run these tests:


```bash
cd ui-tests
#install required packages for jlpm
Expand Down Expand Up @@ -143,7 +179,8 @@ The repository is configured to use the Lerna caching system (via `nx`) for some

This helps speed up rebuilds when running `jlpm run build` multiple times to avoid rebuilding packages that have not changed on disk.

You can generate a graph to have a better idea of the dependencies between all the packages using the following command:

- You can generate a graph to have a better idea of the dependencies between all the packages using the following command:

```
npx nx graph
Expand Down Expand Up @@ -173,46 +210,34 @@ This will trigger a GitHub Action that will run the UI tests automatically and p
## Code Styling

All non-python source code is formatted using [prettier](https://prettier.io) and python source code is formatted using [black](https://github.com/psf/black).
When code is modified and committed, all staged files will be
automatically formatted using pre-commit git hooks (with help from
[pre-commit](https://github.com/pre-commit/pre-commit). The benefit of
using code formatters like `prettier` and `black` is that it removes the topic of
code style from the conversation when reviewing pull requests, thereby
speeding up the review process.

As long as your code is valid,
the pre-commit hook should take care of how it should look.
`pre-commit` and its associated hooks will automatically be installed when
When code is modified and committed, all staged files will be automatically formatted using pre-commit git hooks (with help from [pre-commit])(https://github.com/pre-commit/pre-commit).

The benefit of using code formatters like `prettier` and `black` is that it removes the topic of code style from the conversation when reviewing pull requests
thereby speeding up the review process.

As long as your code is valid, the pre-commit hook should take care of how it should look. `pre-commit` and its associated hooks will automatically be installed when
you run `pip install -e ".[dev,test]"`

To install `pre-commit` manually, run the following:

- To install `pre-commit` manually, run the following:

```shell
pip install pre-commit
pre-commit install
```

You can invoke the pre-commit hook by hand at any time with:
- You can invoke the pre-commit hook by hand at any time with:

```shell
pre-commit run
```

which should run any autoformatting on your code
and tell you about any errors it couldn't fix automatically.
You may also install [black integration](https://github.com/psf/black#editor-integration)
into your text editor to format code automatically.
which should run any autoformatting on your code and tell you about any errors it couldn't fix automatically. You may also install [black integration](https://github.com/psf/black#editor-integration) into your text editor to format code automatically.

If you have already committed files before setting up the pre-commit
hook with `pre-commit install`, you can fix everything up using
`pre-commit run --all-files`. You need to make the fixing commit
yourself after that.
If you have already committed files before setting up the pre-commit hook with `pre-commit install`, you can fix everything up using `pre-commit run --all-files`. You need to make the fixing commit yourself after that.

You may also use the prettier npm script (e.g. `npm run prettier` or
`yarn prettier` or `jlpm 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.
You may also use the prettier npm script (e.g. `npm run prettier` or`yarn prettier` or `jlpm 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.

Some of the hooks only run on CI by default, but you can invoke them by
running with the `--hook-stage manual` argument.
Expand All @@ -221,13 +246,13 @@ running with the `--hook-stage manual` argument.

First make sure you have set up a development environment as described above.

Then run the following command to build the docs:
-Then run the following command to build the docs:

```shell
hatch run docs:build
```

In a separate terminal window, run the following command to serve the documentation:
-In a separate terminal window, run the following command to serve the documentation:

```shell
hatch run docs:serve
Expand All @@ -246,3 +271,6 @@ Alternatively you can also contribute to Jupyter Notebook without setting up a l
- [Gitpod](https://gitpod.io/#https://github.com/jupyter/notebook) integration is enabled. The Gitpod config automatically builds the Jupyter Notebook application and the documentation.
- GitHub’s [built-in editor](https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files) is suitable for contributing small fixes.
- A more advanced [github.dev](https://docs.github.com/en/codespaces/the-githubdev-web-based-editor) editor can be accessed by pressing the dot (.) key while in the Jupyter Notebook GitHub repository


This guide is meant to help both new and experienced contributors quickly set up, test, and improve Jupyter Notebook.
Loading