From 85a4bbc28e1a3b881d53b5b134461e236308ea51 Mon Sep 17 00:00:00 2001 From: Simon Li Date: Sun, 29 May 2022 19:11:57 +0100 Subject: [PATCH] Update Contributing documentation Adds yarn, moves most of CONTRIBUTING.md into https://jupyterhub.readthedocs.io/en/stable/contributing/index.html to reduce duplication --- CONTRIBUTING.md | 133 +---------------------------- docs/source/contributing/setup.rst | 29 ++++--- docs/source/contributing/tests.rst | 74 +++++++++++++++- 3 files changed, 92 insertions(+), 144 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index abcc6e8a..cf4e4755 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,134 +6,9 @@ you can follow the [Jupyter contributor guide](https://jupyter.readthedocs.io/en Make sure to also follow [Project Jupyter's Code of Conduct](https://github.com/jupyter/governance/blob/HEAD/conduct/code_of_conduct.md) for a friendly and welcoming collaborative environment. -## Setting up a development environment +Please see our documentation on - +- [Setting up a development install](https://jupyterhub.readthedocs.io/en/latest/contributing/setup.html) +- [Testing JupyterHub and linting code](https://jupyterhub.readthedocs.io/en/latest/contributing/tests.html) -JupyterHub requires Python >= 3.5 and nodejs. - -As a Python project, a development install of JupyterHub follows standard practices for the basics (steps 1-2). - -1. clone the repo - ```bash - git clone https://github.com/jupyterhub/jupyterhub - ``` -2. do a development install with pip - - ```bash - cd jupyterhub - python3 -m pip install --editable . - ``` - -3. install the development requirements, - which include things like testing tools - - ```bash - python3 -m pip install -r dev-requirements.txt - ``` - -4. install configurable-http-proxy with npm: - - ```bash - npm install -g configurable-http-proxy - ``` - -5. set up pre-commit hooks for automatic code formatting, etc. - - ```bash - pre-commit install - ``` - - You can also invoke the pre-commit hook manually at any time with - - ```bash - pre-commit run - ``` - -## Contributing - -JupyterHub has adopted automatic code formatting so you shouldn't -need to worry too much about your code style. -As long as your code is valid, -the pre-commit hook should take care of how it should look. -You can invoke the pre-commit hook by hand at any time with: - -```bash -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. - -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. - -## Testing - -It's a good idea to write tests to exercise any new features, -or that trigger any bugs that you have fixed to catch regressions. - -You can run the tests with: - -```bash -pytest -v -``` - -in the repo directory. If you want to just run certain tests, -check out the [pytest docs](https://pytest.readthedocs.io/en/latest/usage.html) -for how pytest can be called. -For instance, to test only spawner-related things in the REST API: - -```bash -pytest -v -k spawn jupyterhub/tests/test_api.py -``` - -The tests live in `jupyterhub/tests` and are organized roughly into: - -1. `test_api.py` tests the REST API -2. `test_pages.py` tests loading the HTML pages - -and other collections of tests for different components. -When writing a new test, there should usually be a test of -similar functionality already written and related tests should -be added nearby. - -The fixtures live in `jupyterhub/tests/conftest.py`. There are -fixtures that can be used for JupyterHub components, such as: - -- `app`: an instance of JupyterHub with mocked parts -- `auth_state_enabled`: enables persisting auth_state (like authentication tokens) -- `db`: a sqlite in-memory DB session -- `io_loop`: a Tornado event loop -- `event_loop`: a new asyncio event loop -- `user`: creates a new temporary user -- `admin_user`: creates a new temporary admin user -- single user servers - - `cleanup_after`: allows cleanup of single user servers between tests -- mocked service - - `MockServiceSpawner`: a spawner that mocks services for testing with a short poll interval - - `mockservice`: mocked service with no external service url - - `mockservice_url`: mocked service with a url to test external services - -And fixtures to add functionality or spawning behavior: - -- `admin_access`: grants admin access -- `no_patience`: sets slow-spawning timeouts to zero -- `slow_spawn`: enables the SlowSpawner (a spawner that takes a few seconds to start) -- `never_spawn`: enables the NeverSpawner (a spawner that will never start) -- `bad_spawn`: enables the BadSpawner (a spawner that fails immediately) -- `slow_bad_spawn`: enables the SlowBadSpawner (a spawner that fails after a short delay) - -To read more about fixtures check out the -[pytest docs](https://docs.pytest.org/en/latest/fixture.html) -for how to use the existing fixtures, and how to create new ones. - -When in doubt, feel free to [ask](https://gitter.im/jupyterhub/jupyterhub). +If you need some help, feel free to ask on [Gitter](https://gitter.im/jupyterhub/jupyterhub) or [Discourse](https://discourse.jupyter.org/). diff --git a/docs/source/contributing/setup.rst b/docs/source/contributing/setup.rst index aaad9e57..acd8dcc0 100644 --- a/docs/source/contributing/setup.rst +++ b/docs/source/contributing/setup.rst @@ -16,7 +16,7 @@ Install Python -------------- JupyterHub is written in the `Python `_ programming language, and -requires you have at least version 3.5 installed locally. If you haven’t +requires you have at least version 3.6 installed locally. If you haven’t installed Python before, the recommended way to install it is to use `miniconda `_. Remember to get the ‘Python 3’ version, and **not** the ‘Python 2’ version! @@ -24,11 +24,10 @@ and **not** the ‘Python 2’ version! Install nodejs -------------- -``configurable-http-proxy``, the default proxy implementation for -JupyterHub, is written in Javascript to run on `NodeJS -`_. If you have not installed nodejs before, we -recommend installing it in the ``miniconda`` environment you set up for -Python. You can do so with ``conda install nodejs``. +`NodeJS 12+ `_ is required for building some JavaScript components. +``configurable-http-proxy``, the default proxy implementation for JupyterHub, is written in Javascript. +If you have not installed nodejs before, we recommend installing it in the ``miniconda`` environment you set up for Python. +You can do so with ``conda install nodejs``. Install git ----------- @@ -46,7 +45,7 @@ their effects quickly. You need to do a developer install to make that happen. .. note:: This guide does not attempt to dictate *how* development - environements should be isolated since that is a personal preference and can + environments should be isolated since that is a personal preference and can be achieved in many ways, for example `tox`, `conda`, `docker`, etc. See this `forum thread `_ for a more detailed discussion. @@ -66,7 +65,7 @@ happen. python -V - This should return a version number greater than or equal to 3.5. + This should return a version number greater than or equal to 3.6. .. code:: bash @@ -74,12 +73,11 @@ happen. This should return a version number greater than or equal to 5.0. -3. Install ``configurable-http-proxy``. This is required to run - JupyterHub. +3. Install ``configurable-http-proxy`` (required to run and test the default JupyterHub configuration) and ``yarn`` (required to build some components): .. code:: bash - npm install -g configurable-http-proxy + npm install -g configurable-http-proxy yarn If you get an error that says ``Error: EACCES: permission denied``, you might need to prefix the command with ``sudo``. If you do not @@ -87,11 +85,17 @@ happen. .. code:: bash - npm install configurable-http-proxy + npm install configurable-http-proxy yarn export PATH=$PATH:$(pwd)/node_modules/.bin The second line needs to be run every time you open a new terminal. + If you are using conda you can instead run: + + .. code:: bash + + conda install configurable-http-proxy yarn + 4. Install the python packages required for JupyterHub development. .. code:: bash @@ -186,3 +190,4 @@ development updates, with: python3 setup.py js # fetch updated client-side js python3 setup.py css # recompile CSS from LESS sources + python3 setup.py jsx # build React admin app diff --git a/docs/source/contributing/tests.rst b/docs/source/contributing/tests.rst index c607df92..044aa7ca 100644 --- a/docs/source/contributing/tests.rst +++ b/docs/source/contributing/tests.rst @@ -1,8 +1,8 @@ .. _contributing/tests: -================== -Testing JupyterHub -================== +=================================== +Testing JupyterHub and linting code +=================================== Unit test help validate that JupyterHub works the way we think it does, and continues to do so when changes occur. They also help communicate @@ -57,6 +57,50 @@ Running the tests pytest -v jupyterhub/tests/test_api.py::test_shutdown + See the `pytest usage documentation `_ for more details. + +Test organisation +================= + +The tests live in ``jupyterhub/tests`` and are organized roughly into: + +#. ``test_api.py`` tests the REST API +#. ``test_pages.py`` tests loading the HTML pages + +and other collections of tests for different components. +When writing a new test, there should usually be a test of +similar functionality already written and related tests should +be added nearby. + +The fixtures live in ``jupyterhub/tests/conftest.py``. There are +fixtures that can be used for JupyterHub components, such as: + +- ``app``: an instance of JupyterHub with mocked parts +- ``auth_state_enabled``: enables persisting auth_state (like authentication tokens) +- ``db``: a sqlite in-memory DB session +- ``io_loop```: a Tornado event loop +- ``event_loop``: a new asyncio event loop +- ``user``: creates a new temporary user +- ``admin_user``: creates a new temporary admin user +- single user servers + - ``cleanup_after``: allows cleanup of single user servers between tests +- mocked service + - ``MockServiceSpawner``: a spawner that mocks services for testing with a short poll interval + - ``mockservice```: mocked service with no external service url + - ``mockservice_url``: mocked service with a url to test external services + +And fixtures to add functionality or spawning behavior: + +- ``admin_access``: grants admin access +- ``no_patience```: sets slow-spawning timeouts to zero +- ``slow_spawn``: enables the SlowSpawner (a spawner that takes a few seconds to start) +- ``never_spawn``: enables the NeverSpawner (a spawner that will never start) +- ``bad_spawn``: enables the BadSpawner (a spawner that fails immediately) +- ``slow_bad_spawn``: enables the SlowBadSpawner (a spawner that fails after a short delay) + +See the `pytest fixtures documentation `_ +for how to use the existing fixtures, and how to create new ones. + Troubleshooting Test Failures ============================= @@ -66,3 +110,27 @@ All the tests are failing Make sure you have completed all the steps in :ref:`contributing/setup` successfully, and can launch ``jupyterhub`` from the terminal. + + +Code formatting and linting +=========================== + +JupyterHub has adopted automatic code formatting and linting. +As long as your code is valid, the pre-commit hook should take care of how it should look. +You can invoke the pre-commit hook by hand at any time with: + +.. code:: bash + + 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 `_ +into your text editor to format code automatically. + +If you have already committed files before running pre-commit you can fix everything using: + +.. code:: bash + + pre-commit run --all-files + +And committing the changes.