diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f7bcc425b3..48379e8ec0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,18 +7,18 @@ for a friendly and welcoming collaborative environment. ## Setting up a development environment -Note: You will need NodeJS to build the extension package. +**Note**: you will need Node.js installed to build the extension package. The `jlpm` command is JupyterLab's pinned version of [yarn](https://yarnpkg.com/) that is installed with JupyterLab. You may use `yarn` or `npm` in lieu of `jlpm` below. -**Note**: we recommend using `mamba` to speed the creating of the environment. +**Note**: we recommend using `mamba` to speed up environment creation. ```bash -# create a new environment +# Create a new environment mamba create -n notebook -c conda-forge python nodejs -y -# activate the environment +# Activate the environment mamba activate notebook # Install package in development mode @@ -47,7 +47,7 @@ There is also a `watch` script to watch for changes and rebuild the app automati jlpm watch ``` -To make sure the `notebook` server extension is installed: +To make sure the `notebook` server extension is enabled: ```bash $ jupyter server extension list @@ -74,7 +74,7 @@ jupyter notebook The development installation described above fetches JavaScript dependencies from [npmjs](https://www.npmjs.com/), according to the versions in the _package.json_ file. -However, it is sometimes useful to be able to test changes in Notebook, with dependencies (e.g. `@jupyterlab` packages) that have not yet +However, it is sometimes useful to be able to test changes in Notebook, with dependencies (e.g., `@jupyterlab` packages) that have not yet been published. [yalc](https://github.com/wclr/yalc) can help use local JavaScript packages in your build of @@ -82,12 +82,12 @@ 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.\ +- From the package root directory, publish your dependency package:\ + `yalc publish`\ 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:\ + - 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 @@ -99,8 +99,8 @@ Notebook, acting as a local package repository. 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.\ +**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. @@ -117,20 +117,20 @@ There are also end to end tests to cover higher level user interactions, located ```bash cd ui-tests -#install required packages for jlpm +# Install required packages for jlpm jlpm -#install playwright +# Install Playwright jlpm playwright install -# start a new Jupyter server in a terminal +# Start a new Jupyter server in a terminal jlpm start -# in a new terminal, run the tests +# In a new terminal, run the tests jlpm test ``` -The `test` script calls the Playwright test runner. You can pass additional arguments to `playwright` by appending parameters to the command. For example to run the test in headed mode, `jlpm test --headed`. +The `test` script calls the Playwright test runner. You can pass additional arguments to `playwright` by appending parameters to the command. For example, to run the test in headed mode, `jlpm test --headed`. Check out the [Playwright Command Line Reference](https://playwright.dev/docs/test-cli/) for more information about the available command line options. @@ -163,7 +163,7 @@ To learn more about Lerna caching: Often a PR might make changes to the user interface, which can cause the visual regression tests to fail. -If you want to update the reference snapshots while working on a PR you can post the following sentence as a GitHub comment: +If you want to update the reference snapshots while working on a PR, you can post the following sentence as a GitHub comment: ``` bot please update playwright snapshots @@ -173,11 +173,11 @@ 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). +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 +automatically formatted using pre-commit git hooks with help from [pre-commit](https://github.com/pre-commit/pre-commit). The benefit of -using a code formatters like `prettier` and `black` is that it removes the topic 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. @@ -201,17 +201,16 @@ 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) +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. +`pre-commit run --all-files`. You'll need to commit the fixes manually 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 +You may also run Prettier using a script (e.g., `npm run prettier`, +`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. @@ -220,9 +219,9 @@ running with the `--hook-stage manual` argument. ## Documentation -First make sure you have set up a development environment as described above. +First, make sure you have set up a development environment as described above. -Then run the following command to build the docs: +Run the following command to build the docs: ```shell hatch run docs:build @@ -234,16 +233,16 @@ In a separate terminal window, run the following command to serve the documentat hatch run docs:serve ``` -Now open a web browser and navigate to `http://localhost:8000` to access the documentation. +Now, open a web browser and navigate to `http://localhost:8000` to access the documentation. ## Contributing from the browser -Alternatively you can also contribute to Jupyter Notebook without setting up a local environment, directly from a web browser: +Alternatively, you can contribute to Jupyter Notebook without setting up a local environment, directly from a web browser: -- [GitHub CodeSpaces](https://github.com/codespaces) is directly integrated into GitHub. This repository uses the [pixi](https://pixi.sh/) package manager to set up the development environment. To contribute after the Codespace is started: - - Run `pixi shell` in a terminal to activate the development environment +- [GitHub CodeSpaces](https://github.com/codespaces) is directly integrated into GitHub. This repository uses the [Pixi](https://pixi.sh/) package manager to set up the development environment. To contribute after the Codespace is started: + - Run `pixi shell` in a terminal to activate the development environment. - Use the commands above for building the extension and running the tests, for example: `jlpm build` - To start the application: `pixi run start`. A popup should appear with a button to open the Jupyter Notebook in a new browser tab. If the popup does not appear, you can navigate to the "Forwarded ports" panel to find the URL to the application. - [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 +- 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.