CONTRIBUTING.md 3.06 KB
Newer Older
1
# Contributing
Jeremy Tuloup's avatar
Jeremy Tuloup committed
2

3
Thanks for contributing to JupyterLite!
Jeremy Tuloup's avatar
Jeremy Tuloup committed
4

5
6
> We follow [Project Jupyter's Code of Conduct][coc] for a friendly and welcoming
> collaborative environment.
Jeremy Tuloup's avatar
Jeremy Tuloup committed
7

8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
## Setup

### Get the code

```bash
git clone https://github.com/jtpio/jupyterlite
```

> if you don't have `git` yet, you might be able to use the instructions below to get it

### Prerequisites

You'll need:

- `git`
- `nodejs >=12`
- `yarn <2`

Various package managers on different operating systems provide these.

> A recommended approach for _any platform_ is to install [Mambaforge] and use the
> binder environment description checked into the repo.
>
> ```bash
> mamba env update --file .binder/environment.yml
> mamba activate jupyterlite-dev
> ```

## Development Tasks

### JavaScript development

#### Quick start

Most of the [development tasks](#development-tasks) can be run with one command:

```bash
yarn bootstrap
```

#### Install

```bash
yarn
```

#### Build

To build development assets:

```bash
yarn build
```

To build production assets:

```bash
yarn build:prod
```

68
69
#### Serve

70
71
72
73
74
75
76
> These are **not real server solutions**, but they _will_ serve all of the assets types
> (including `.wasm`) correctly for JupyterLite under development, testing, and demo
> purposes.

To serve with `scripts/serve.js`, based on Node.js's
[`http`](https://nodejs.org/api/http.html) module:

77
78
79
80
```
yarn serve
```

81
82
83
To serve with Python's built-in
[`http.server`](https://docs.python.org/3/library/http.server.html) module (requires
Python 3.7+):
84
85
86
87
88

```
yarn serve:py
```

89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
#### Watch

```bash
yarn watch
```

#### Lint

```bash
yarn lint
```

#### Test

```bash
yarn build:test
yarn test
```

## Community Tasks

### Issues

JupyterLite features and bug fixes start as [issues] on GitHub.

- Look through the existing issues (and [pull requests]!) to see if a related issue
  already exists or is being worked on
- If it is new:
  - Start a [new issue]
  - Pick an appropriate template
  - Fill out the template
  - Wait for the community to respond

### Pull Requests

JupyterLite become _real_ as [pull requests].

> Pull requests are a great place to discuss work-in-progress, but it is **highly
> recommended** to create an [issue](#issues) before starting work so the community can
> weigh in on choices.

- Fork the repo
- Make a new branch off `main`
- Make changes
- Run the `lint` and `test`
- Push to your fork
- Start the pull request
  - your `git` cli should offer you a link, as will the GitHub web UI
  - reference one or more [issue](#issues) so those that are interested can find your
    work
    - adding magic strings like `fixes #123` help tie the collaboration history together
- Wait for continuous integration
  - If stuff breaks, fix it or ask for help!

### Releasing

> TBD

[issues]: https://github.com/jtpio/jupyterlite/issues
[new issue]: https://github.com/jtpio/jupyterlite/issues/new
[pull requests]: https://github.com/jtpio/jupyterlite/pulls
[repo]: https://github.com/jtpio/jupyterlite
151
152
[coc]: https://github.com/jupyter/governance/blob/master/conduct/code_of_conduct.md
[mambaforge]: https://github.com/conda-forge/miniforge