CONTRIBUTING.md 4.49 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
## Setup

Nicholas Bollweg's avatar
Nicholas Bollweg committed
10
### Get the Code
11
12
13
14
15
16
17
18
19
20
21
22
23
24

```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`
25
- `python >=3.8`
Romain Casati's avatar
Typo.    
Romain Casati committed
26
27
28
29
- `black`
- `flit`
- `sphinx`
- `pytest-check-links`
30
31
32
33
34
35
36
37
38
39
40
41
42

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

43
44
45
46
47
48
### doit

[doit](https://github.com/pydoit/doit) handles the full software lifecycle, spanning
JavaScript to documentation building. It understands the dependencies between different
nested _tasks_, usually as files that change on disk.

Nicholas Bollweg's avatar
Nicholas Bollweg committed
49
#### List Tasks
50
51
52
53
54
55
56
57
58
59
60
61
62
63

To see all of the _tasks_ available, use the `list` action:

```bash
doit list --all --status
```

To get information about a specific _task_, use the info `info` _action_ with the _task_
name from the first column of `list`:

```bash
doit info build:js:app:classic
```

Nicholas Bollweg's avatar
Nicholas Bollweg committed
64
#### Task and Action Defaults
65
66
67
68
69
70
71
72
73
74
75
76

The default `doit` _action_ is `run` which... runs the named _tasks_.

The default tasks are `lint` and `build`, which do basically everything performed by
continuous integration, so the following are equivalent:

```bash
doit
doit lint build
doit run lint build
```

77
78
### JavaScript development

79
80
81
While most of the scripts below will be run (in the correct order based on changes) by
`doit`, the following _scripts_ (defined in `package.json`) are worth highlighting.

82
83
84
85
86
87
88
89
#### Quick start

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

```bash
yarn bootstrap
```

Nicholas Bollweg's avatar
Nicholas Bollweg committed
90
#### Install JavaScript Dependencies
91
92
93
94
95

```bash
yarn
```

Nicholas Bollweg's avatar
Nicholas Bollweg committed
96
#### Build Apps
97
98
99
100
101
102
103
104
105
106
107
108
109

To build development assets:

```bash
yarn build
```

To build production assets:

```bash
yarn build:prod
```

Nicholas Bollweg's avatar
Nicholas Bollweg committed
110
#### Serve Apps
111

112
113
114
115
116
117
118
> 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:

119
120
121
122
```
yarn serve
```

123
124
125
To serve with Python's built-in
[`http.server`](https://docs.python.org/3/library/http.server.html) module (requires
Python 3.7+):
126
127
128
129
130

```
yarn serve:py
```

Nicholas Bollweg's avatar
Nicholas Bollweg committed
131
#### Watch Sources
132
133
134
135
136

```bash
yarn watch
```

Nicholas Bollweg's avatar
Nicholas Bollweg committed
137
#### Lint/Format Sources
138
139
140
141
142

```bash
yarn lint
```

Nicholas Bollweg's avatar
Nicholas Bollweg committed
143
#### Run Unit Tests
144
145
146
147
148
149

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

150
151
152
153
154
155
### Documentation

The documentation site, served on readthedocs.io, uses information from different parts
of the software lifecycle (e.g. contains a copy of the built `app` directory), so using
the [doit](#doit) tools are recommended.

Nicholas Bollweg's avatar
Nicholas Bollweg committed
156
#### Build Documentation
157
158
159
160
161

```bash
doit docs
```

Nicholas Bollweg's avatar
Nicholas Bollweg committed
162
#### Watch Documentation
163
164
165
166
167

```bash
doit watch:docs
```

168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
## 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
193
- Run `doit lint test`
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
- 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
211
212
[coc]: https://github.com/jupyter/governance/blob/master/conduct/code_of_conduct.md
[mambaforge]: https://github.com/conda-forge/miniforge