Skip to content

Commit 2e64ce3

Browse files
T4rk1nT4rk1n
authored
Merge pull request #2893 from aGitForEveryone/windows-user-friendly-contribute
Made CONTRIBUTING guide more (windows-)user friendly
2 parents 7926f05 + 8173cfe commit 2e64ce3

File tree

1 file changed

+120
-24
lines changed

1 file changed

+120
-24
lines changed

‎CONTRIBUTING.md

Lines changed: 120 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,136 @@
11
# Contributor Guide
22

33
## 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.
45

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.
68

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:
793
```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
1794
$ pip install -e .[ci,dev,testing,celery,diskcache] # in some shells you need \ to escape []
1895
$ 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
29114
$ 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
33121
$ 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
35126
$ pip list | grep dash
36127
```
37128

129+
The output should look like this:
130+
```bash
131+
dash <version number> /path/to/local/dash/repo/
132+
```
133+
38134
### Dash-Renderer Beginner Guide
39135

40136
`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

Comments
 (0)