Skip to content

Commit

Permalink
docs: update contributing guide to explicitly require running `make i…
Browse files Browse the repository at this point in the history
…nstall`

Closes: #1678
  • Loading branch information
kgryte committed Mar 20, 2024
1 parent 09483ae commit 105db06
Showing 1 changed file with 32 additions and 12 deletions.
44 changes: 32 additions & 12 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -152,7 +152,27 @@ And finally, add an `upstream` [remote][git-remotes] to allow syncing changes be
$ git remote add upstream git://github.com/stdlib-js/stdlib.git
```

#### Step 2: Branch
#### Step 2: Initial Setup

Install dependencies.

<!-- run-disable -->

```bash
$ make install
```

Initialize Git hooks to enable automated development processes to run prior to authoring commits and pushing changes.

<!-- run-disable -->

```bash
$ make init
```

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.

#### Step 3: Branch

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

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

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.

#### Step 3: Write
#### Step 4: Write

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.

#### Step 4: Commit
#### Step 5: Commit

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

Expand All @@ -190,7 +210,7 @@ $ git commit

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.

#### Step 5: Sync
#### Step 6: Sync

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:

Expand All @@ -206,7 +226,7 @@ $ git fetch upstream
$ git rebase upstream/develop
```

#### Step 6: Test
#### Step 7: Test

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

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

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

#### Step 7: Push
#### Step 8: Push

Push your changes to your remote GitHub repository.

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

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

#### Step 8: Pull Request
#### Step 9: Pull Request

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.

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

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.

#### Step 9: Land
#### Step 10: Land

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.

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

#### Step 10: Celebrate
#### Step 11: Celebrate

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

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

```bash
$ make TESTS_FILTER=.*/<pattern>/.* test
$ make TESTS_FILTER=".*/<pattern>/.*" test
```

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

<!-- run-disable -->

```bash
$ make TESTS_FILTER=.*/math/base/special/sin/.* test
$ make TESTS_FILTER=".*/math/base/special/sin/.*" test
```

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

```bash
$ make TESTS_FILTER=.*/<pattern>/.* test-cov
$ make TESTS_FILTER=".*/<pattern>/.*" test-cov
$ make view-cov
```

Expand Down

0 comments on commit 105db06

Please sign in to comment.