diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d17c5a0314..92ed10153b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 @@ -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/), @@ -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. @@ -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 @@ -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 @@ -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. @@ -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 @@ -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.