|
1 | 1 | # Contributor Guide |
2 | 2 |
|
3 | 3 | ## Getting Started |
| 4 | +Glad that you decided to make your contribution in Dash. This guide provides instructions to set up and build the Dash repository and describes best practices when contributing to the Dash repository. |
4 | 5 |
|
5 | | -Glad that you decided to make your contribution in Dash, to set up your development environment, run the following commands: |
| 6 | +### Fork the Dash repository |
| 7 | +When contributing to the Dash repository you should always work in your own copy of the Dash repository. Create a fork of the `dev`-branch, to create a copy of the Dash repository in your own GitHub account. See official instructions for [creating a fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) if needed. |
6 | 8 |
|
| 9 | +Clone the forked repository (either option will work). Replace `<your_user_name>` with your user name. |
| 10 | +``` |
| 11 | +git clone https://github.com/<your_user_name>/dash.git |
| 12 | +``` |
| 13 | +or |
| 14 | +``` |
| 15 | +git clone [email protected]:<your_user_name>/dash.git |
| 16 | +``` |
| 17 | + |
| 18 | +When working on a new feature, always create a new branch and create the feature in that branch. For more best practices, read the [Git section](#git). |
| 19 | + |
| 20 | +### Configuring your system |
| 21 | + |
| 22 | +<details> |
| 23 | + <summary>For JavaScript beginners: What are nvm, npm and Node?</summary> |
| 24 | + |
| 25 | + If you are new to JavaScript, many aspects of setting up a working environment and working with the new ecosystem can be a bit overwhelming. Especially if Plotly Dash is your first experience with the JavaScript ecosystem. This section explains common terms that are used when working with JavaScript environments: `nvm`, `Node`, and `npm` |
| 26 | + - `nvm` stands for Node Version Manager. This is a tool that allows you to manage Node installations. Quite convenient if you are working on multiple tools that require different versions of Node.js. `nvm` allows you to switch between Node installations with a single command. |
| 27 | + - `Node.js` is the actual JavaScript runtime environment. Visit the [official site](https://nodejs.org/en) for more info. Don't download Node just yet, install it through `nvm`. |
| 28 | + - `npm` stands for Node Package Manager. This is the largest software registry for JavaScript packages. Check the [official site](https://docs.npmjs.com/about-npm) for more info. |
| 29 | + |
| 30 | + --- |
| 31 | +</details> |
| 32 | + |
| 33 | +<details> |
| 34 | + |
| 35 | +<summary>Installing JavaScript on your system</summary> |
| 36 | + |
| 37 | + > **For Windows users**: `nvm` is not integrated in Windows so a third-party tool needs to be used. If you don't have one yet, you can start with [NVM for Windows](https://github.com/coreybutler/nvm-windows) (`nvm-windows`). This version manager is widely used and is well recommended. |
| 38 | + > |
| 39 | + > Carefully follow the installation instructions listed on the GitHub page. As recommended by the installation instructions there: uninstall any pre-existsing Node installations. You will run into permission errors otherwise. |
| 40 | +
|
| 41 | + With `nvm` available from the command line open any terminal of your preference and install Node and npm: |
| 42 | + ``` |
| 43 | + nvm install latest |
| 44 | + ``` |
| 45 | + After installation is complete, activate the Node environment (**admin access required**) |
| 46 | + ``` |
| 47 | + nvm use latest |
| 48 | + ``` |
| 49 | + Confirm that the activation was successfull |
| 50 | + ``` |
| 51 | + node -v |
| 52 | + npm -v |
| 53 | + ``` |
| 54 | + If these commands are not recognized, close the terminal, re-open a new instance and retry. If the commands return a version number, you have set up your JavaScript environment successfully! |
| 55 | + |
| 56 | + --- |
| 57 | +</details> |
| 58 | + |
| 59 | +## Building Dash |
| 60 | +### For Windows users: use a Bash terminal |
| 61 | +The scripts that run during the build process are designed for a Bash terminal. The default terminals on Windows systems are either PowerShell or Command Prompt. However, the build process will fail (potentially bricking your Node environment) when using these terminals. |
| 62 | + |
| 63 | +The listed commands should be executed from a Bash terminal, e.g. you can use the Git Bash terminal (which is normally installed when installing Git using the default settings). Otherwise, you need to find another way to access a Bash terminal. |
| 64 | + |
| 65 | +### Build process |
| 66 | +The build process is mostly the same for Windows and Linux systems. Wherever there are differences between the operating systems, it is marked. |
| 67 | + |
| 68 | +<details> |
| 69 | + <summary> Pycharm automatically loads Python environments! </summary> |
| 70 | + |
| 71 | + If you work in Pycharm you can open the Dash repo directory as a project (`File -> Open` then browse for the `dash` directory containing your dash repo, and open the directory as a project). You can configure your Python virtual environment using the Python Interpreter tool. |
| 72 | + |
| 73 | + Secondly, you can open the Git Bash terminal in Pycharm and it will automatically activate your selected Python Interpreter in the terminal. You can verify this by executing `pip --version` in the Git Bash terminal, it will show you the path from where pip is run, which is the path where your virtual environment is installed. If you follow these steps, you can skip the first few steps in the overview below. |
| 74 | + |
| 75 | + --- |
| 76 | +</details> |
| 77 | + |
| 78 | +Open a Bash terminal in the `dash` repository, Git Bash terminal for example on Windows. Create and activate virtual environment (skip this part if you manage the Python Interpreter via Pycharm): |
| 79 | +- Linux/Mac: |
| 80 | + |
| 81 | + On some Linux/Mac environments, use `.` instead of `source` |
| 82 | + ```bash |
| 83 | + $ python3 -m venv .venv/dev |
| 84 | + $ source .venv/dev/bin/activate |
| 85 | + ``` |
| 86 | +- Windows: |
| 87 | + ```bash |
| 88 | + $ python -m venv .venv/dev |
| 89 | + $ source .venv/dev/scripts/activate |
| 90 | + ``` |
| 91 | + |
| 92 | +Install dash and dependencies: |
7 | 93 | ```bash |
8 | | -# in your working directory |
9 | | -$ git clone [email protected]:plotly/dash.git |
10 | | -$ cd dash |
11 | | -$ python3 -m venv .venv/dev |
12 | | -# activate the virtualenv |
13 | | -# on windows `.venv\dev\scripts\activate` |
14 | | -# on some linux / mac environments, use `.` instead of `source` |
15 | | -$ source .venv/dev/bin/activate |
16 | | -# install dash and dependencies |
17 | 94 | $ pip install -e .[ci,dev,testing,celery,diskcache] # in some shells you need \ to escape [] |
18 | 95 | $ npm ci |
19 | | -# this script will build the dash-core-components, dash-html-components, dash-table, |
20 | | -# and renderer bundles; this will build all bundles from source code in their |
21 | | -# respective directories. The only true source of npm version is defined |
22 | | -# in package.json for each package. |
23 | | -# |
24 | | -$ npm run build # runs `renderer build` and `npm build` in dcc, html, table |
25 | | -# build and install components used in tests |
26 | | -# on windows, the developer will need to use `npm run first-build` this performs additional first steps |
27 | | -# |
28 | | -# Alternatively one could run part of the build process e.g. |
| 96 | +``` |
| 97 | +`npm ci` does a clean install of all packages listed in package-lock.json. Package versions will be exactly like stated in the file. |
| 98 | + |
| 99 | +Next, build dash-core-components, dash-html-components, dash-table, and renderer bundles. This will build all bundles from source code in their respective directories. The only true source of npm version is defined in package.json for each package: |
| 100 | +- Linux/Mac: |
| 101 | + ```bash |
| 102 | + $ npm run build # runs `renderer build` and `npm build` in dcc, html, table |
| 103 | + ``` |
| 104 | + |
| 105 | +- Windows: |
| 106 | + |
| 107 | + On Windows the build is done via the first-build script. This adds extra steps that are automatically applied on Linux systems, but not on Windows systems: |
| 108 | + ```bash |
| 109 | + $ npm run first-build |
| 110 | + ``` |
| 111 | + |
| 112 | +When you first clone the repository, and check out a new branch, you must run the full build as above. Later on, when you only work in one part of the library, you could run part of the build process e.g. |
| 113 | +```bash |
29 | 114 | $ dash-update-components "dash-core-components" |
30 | | -# to only build dcc when developing dcc |
31 | | -# But when you first clone check out a new branch, you must run the full build as above. |
32 | | -# |
| 115 | + |
| 116 | +``` |
| 117 | +to only build dcc when developing dcc. |
| 118 | + |
| 119 | +Build and install components used in tests: |
| 120 | +```bash |
33 | 121 | $ npm run setup-tests.py # or npm run setup-tests.R |
34 | | -# you should see dash points to a local source repo |
| 122 | +``` |
| 123 | + |
| 124 | +Finally, check that the installation succeeded by checking the output of this command: |
| 125 | +```bash |
35 | 126 | $ pip list | grep dash |
36 | 127 | ``` |
37 | 128 |
|
| 129 | +The output should look like this: |
| 130 | +```bash |
| 131 | +dash <version number> /path/to/local/dash/repo/ |
| 132 | +``` |
| 133 | + |
38 | 134 | ### Dash-Renderer Beginner Guide |
39 | 135 |
|
40 | 136 | `Dash Renderer` began as a separate repository. It was merged into the main `Dash` repository as part of the 1.0 release. It is the common frontend for all Dash backends (**R** and **Python**), and manages React Component layout and backend event handling. |
|
0 commit comments