Skip to content

Commit 105db06

Browse files
committed
docs: update contributing guide to explicitly require running make install
Closes: #1678
1 parent 09483ae commit 105db06

File tree

1 file changed

+32
-12
lines changed

1 file changed

+32
-12
lines changed

CONTRIBUTING.md

Lines changed: 32 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -152,7 +152,27 @@ And finally, add an `upstream` [remote][git-remotes] to allow syncing changes be
152152
$ git remote add upstream git://github.com/stdlib-js/stdlib.git
153153
```
154154

155-
#### Step 2: Branch
155+
#### Step 2: Initial Setup
156+
157+
Install dependencies.
158+
159+
<!-- run-disable -->
160+
161+
```bash
162+
$ make install
163+
```
164+
165+
Initialize Git hooks to enable automated development processes to run prior to authoring commits and pushing changes.
166+
167+
<!-- run-disable -->
168+
169+
```bash
170+
$ make init
171+
```
172+
173+
Note that `make init` only needs to be run once; however, we repeat it below as **not** running it is a common omission by new contributors.
174+
175+
#### Step 3: Branch
156176

157177
For modifications intended to be included in stdlib, create a new local branch.
158178

@@ -164,11 +184,11 @@ $ git checkout -b <branch>
164184

165185
where `<branch>` is the branch name. Both the `master` and `develop` branches for the main stdlib project are protected, and direct modifications to these branches will **not** be accepted. Instead, all contributions should be made on non-master and non-develop local branches, including documentation changes and other non-code modifications. See the project [branching guide][stdlib-branching] for additional guidance.
166186

167-
#### Step 3: Write
187+
#### Step 4: Write
168188

169189
Start making your changes and/or implementing the new feature. Any text you write should follow the [text style guide][stdlib-style-guides-text], including comments and API documentation.
170190

171-
#### Step 4: Commit
191+
#### Step 5: Commit
172192

173193
Ensure that you have configured [Git][git] to know your name and email address.
174194

@@ -190,7 +210,7 @@ $ git commit
190210

191211
When writing commit messages, follow the Git [style guide][stdlib-style-guides-git]. Adherence to project commit conventions is necessary for project automation which automatically generates release notes and changelogs from commit messages.
192212

193-
#### Step 5: Sync
213+
#### Step 6: Sync
194214

195215
To incorporate recent changes from the `upstream` repository during development, you should [rebase][git-rebase] your local branch, reapplying your local commits on top of the current upstream `HEAD`. This procedure is in contrast to performing a standard [merge][git-merge], which may interleave development histories. The rationale is twofold:
196216

@@ -206,7 +226,7 @@ $ git fetch upstream
206226
$ git rebase upstream/develop
207227
```
208228

209-
#### Step 6: Test
229+
#### Step 7: Test
210230

211231
Tests should accompany **all** bug fixes and features. For guidance on how to write tests, consult existing tests within the project.
212232

@@ -222,7 +242,7 @@ linting should be automatically triggered prior to each commit, and test executi
222242

223243
Any [pull requests][github-pull-request] which include failing tests and/or lint errors will **not** be accepted.
224244

225-
#### Step 7: Push
245+
#### Step 8: Push
226246

227247
Push your changes to your remote GitHub repository.
228248

@@ -234,7 +254,7 @@ $ git push origin <branch>
234254

235255
where `<branch>` is the name of your branch.
236256

237-
#### Step 8: Pull Request
257+
#### Step 9: Pull Request
238258

239259
Once your contribution is ready to be incorporated in the `upstream` repository, open a [pull request][github-pull-request] against the `develop` branch. One or more project contributors will review the contribution, provide feedback, and potentially request changes.
240260

@@ -280,13 +300,13 @@ $ git commit -m "fixup! feat: add support for computing the absolute value"
280300

281301
If the history needs modification, a contributor will modify the history during the merge process. The rationale for **not** rewriting public history is that doing so invalidates the commit history for anyone else who has pulled your changes, thus imposing additional burdens on collaborators to ensure that their local versions match the modified history.
282302

283-
#### Step 9: Land
303+
#### Step 10: Land
284304

285305
After any changes have been resolved and continuous integration tests have passed, a contributor will approve a [pull request][github-pull-request] for inclusion in the project. Once merged, the [pull request][github-pull-request] will be updated with the merge commit, and the [pull request][github-pull-request] will be closed.
286306

287307
Note that, during the merge process, multiple commits will often be [squashed][git-rewriting-history].
288308

289-
#### Step 10: Celebrate
309+
#### Step 11: Celebrate
290310

291311
**Congratulations**! You are an official contributor to stdlib! Thank you for your hard work and patience!
292312

@@ -316,15 +336,15 @@ The project can **never** have enough tests. To address areas lacking sufficient
316336
<!-- run-disable -->
317337

318338
```bash
319-
$ make TESTS_FILTER=.*/<pattern>/.* test
339+
$ make TESTS_FILTER=".*/<pattern>/.*" test
320340
```
321341

322342
where `<pattern>` is a pattern matching a particular path. For example, to test the base math `sin` package
323343

324344
<!-- run-disable -->
325345

326346
```bash
327-
$ make TESTS_FILTER=.*/math/base/special/sin/.* test
347+
$ make TESTS_FILTER=".*/math/base/special/sin/.*" test
328348
```
329349

330350
where the pattern `.*/math/base/special/sin/.*` matches any test file whose absolute path contains `math/base/special/sin`.
@@ -334,7 +354,7 @@ The project can **never** have enough tests. To address areas lacking sufficient
334354
<!-- run-disable -->
335355

336356
```bash
337-
$ make TESTS_FILTER=.*/<pattern>/.* test-cov
357+
$ make TESTS_FILTER=".*/<pattern>/.*" test-cov
338358
$ make view-cov
339359
```
340360

0 commit comments

Comments
 (0)