You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/contributing/FAQ.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -46,7 +46,7 @@ limitations under the License.
46
46
47
47
## Introduction
48
48
49
-
We appreciate your interest in contributing to stdlib! Below, we’ve compiled answers to some frequently asked questions (FAQs) from first-time contributors. If you’re new to the project or encounter any challenges, this guide is a great place to start.
49
+
We appreciate your interest in contributing to stdlib! Below, we've compiled answers to some frequently asked questions (FAQs) from first-time contributors. If you're new to the project or encounter any challenges, this guide is a great place to start.
> In [Git][git], a [remote][github-remote] is a reference to a repository. Your fork is called `origin`, while the official `stdlib` repository is referred to as `upstream`. Adding an [upstream][git-remotes] remote allows you to consistently fetch the latest updates from the original repository and incorporate them into your work.
@@ -81,47 +81,47 @@ In `stdlib`, the `develop` branch is the primary branch for development. Instead
81
81
<!-- run-disable -->
82
82
83
83
```bash
84
-
git checkout -b feature/my-new-feature
84
+
$ git checkout -b feature/my-new-feature
85
85
```
86
86
87
87
## Changes
88
88
89
-
Now comes the fun part of actually writing code! After making your changes, it's always good to check what’s modified:
89
+
Now comes the fun part of actually writing code! After making your changes, it's always good to check what's modified:
90
90
91
91
<!-- run-disable -->
92
92
93
93
```bash
94
-
git status
94
+
$ git status
95
95
```
96
96
97
97
Once you're happy with your changes, add them to the staging area for a final confirmation:
98
98
99
99
<!-- run-disable -->
100
100
101
101
```bash
102
-
git add <file1><file2># Add specific files
103
-
git add .# Add all changes
102
+
$ git add <file1><file2># Add specific files
103
+
$ git add .# Add all changes
104
104
```
105
105
106
106
Then, commit with a meaningful message:
107
107
108
108
<!-- run-disable -->
109
109
110
110
```bash
111
-
git commit -m "feat: add support for new function"
111
+
$ git commit -m "feat: add support for new function"
112
112
```
113
113
114
114
For **multi-line** commit messages (like when you want to include a longer description), you can use:
115
115
116
116
<!-- run-disable -->
117
117
118
118
```bash
119
-
git commit
119
+
$ git commit
120
120
```
121
121
122
122
This opens an editor where you can write something like:
123
123
124
-
```bash
124
+
```plaintext
125
125
feat: add support for new function
126
126
127
127
This adds the initial version of <function_name>, with support for <brief explanation>.
@@ -140,7 +140,7 @@ To make this even easier, you can also use:
140
140
<!-- run-disable -->
141
141
142
142
```bash
143
-
make commit
143
+
$ make commit
144
144
```
145
145
146
146
This gives you an interactive prompt to help you craft a properly formatted commit message. Super handy!
@@ -154,15 +154,15 @@ Once your branch is ready, you need to push your **local** changes to your forke
154
154
<!-- run-disable -->
155
155
156
156
```bash
157
-
git push
157
+
$ git push
158
158
```
159
159
160
-
If this is the first time you’re pushing the branch, [Git][git] may prompt you to set an [upstream][git-remotes] branch. You can do this manually by running:
160
+
If this is the first time you're pushing the branch, [Git][git] may prompt you to set an [upstream][git-remotes] branch. You can do this manually by running:
> **Note:** This is a **one-time setup** for this branch. After this, you can simply use `git push` for future updates.
@@ -188,8 +188,8 @@ To update your local `develop` branch while making sure there are no unwanted ch
188
188
<!-- run-disable -->
189
189
190
190
```bash
191
-
git checkout develop
192
-
git pull --ff-only upstream develop
191
+
$ git checkout develop
192
+
$ git pull --ff-only upstream develop
193
193
```
194
194
195
195
> **Why use `--ff-only`?** This ensures your branch updates **only if no merge commits are needed**. If your `develop` branch has unexpected changes, this command will fail, alerting you that something is wrong.
@@ -199,8 +199,8 @@ If the above pull fails because you accidentally made changes to `develop`, you
199
199
<!-- run-disable -->
200
200
201
201
```bash
202
-
git checkout develop
203
-
git reset --hard upstream/develop
202
+
$ git checkout develop
203
+
$ git reset --hard upstream/develop
204
204
```
205
205
206
206
> **Warning:** This will delete any changes you made to `develop`. Make sure you don't have important work in this branch before running this command.
@@ -210,7 +210,7 @@ After updating `develop`, you can push it to your fork to keep everything in syn
210
210
<!-- run-disable -->
211
211
212
212
```bash
213
-
git push origin develop
213
+
$ git push origin develop
214
214
```
215
215
216
216
## Integration
@@ -226,17 +226,17 @@ Rebasing **moves** your commits on top of the latest `develop`, as if you had st
226
226
<!-- run-disable -->
227
227
228
228
```bash
229
-
git checkout feature/my-branch
230
-
git rebase develop
229
+
$ git checkout feature/my-branch
230
+
$ git rebase develop
231
231
```
232
232
233
233
If there are conflicts, resolve them and continue:
234
234
235
235
<!-- run-disable -->
236
236
237
237
```bash
238
-
git add <resolved-file>
239
-
git rebase --continue
238
+
$ git add <resolved-file>
239
+
$ git rebase --continue
240
240
```
241
241
242
242
#### Example: How Rebase Works
@@ -266,16 +266,16 @@ Merging **combines** your feature branch with `develop`, keeping both histories
266
266
<!-- run-disable -->
267
267
268
268
```bash
269
-
git checkout feature/my-branch
270
-
git merge develop
269
+
$ git checkout feature/my-branch
270
+
$ git merge develop
271
271
```
272
272
273
273
If there are conflicts, resolve them, then commit the merge. Finally, push the updated branch:
274
274
275
275
<!-- run-disable -->
276
276
277
277
```bash
278
-
git push origin feature/my-branch
278
+
$ git push origin feature/my-branch
279
279
```
280
280
281
281
> Alternatively, if you have a running PR and want to update that branch directly to the `stdlib` develop branch, comment `/stdlib merge` on the PR, wait for the bot to merge your branch automatically, and then run `git pull`.
@@ -307,7 +307,7 @@ Use **Rebase** if:
307
307
308
308
Use **Merge** if:
309
309
310
-
- You want a safer approach that doesn’t rewrite history.
310
+
- You want a safer approach that doesn't rewrite history.
311
311
- You are unsure about rebase or are collaborating on the branch.
312
312
313
313
> **When in doubt, use merge.** It is safer and avoids potential conflicts caused by rewriting history. If you use the GitHub UI to update your branches, it also performs a merge.
@@ -354,16 +354,16 @@ We will consider the conflict in the `isEven` function above. Let's say you want
354
354
<!-- run-disable -->
355
355
356
356
```bash
357
-
git add <file>
357
+
$ git add <file>
358
358
```
359
359
360
360
- Continue the rebase or merge:
361
361
362
362
<!-- run-disable -->
363
363
364
364
```bash
365
-
git rebase --continue # If rebasing
366
-
git merge --continue # If merging
365
+
$ git rebase --continue # If rebasing
366
+
$ git merge --continue # If merging
367
367
```
368
368
369
369
> **Tip:** Many editors like VS Code highlight conflicts and even give you buttons to accept incoming or current changes. This can make resolving conflicts much easier.
@@ -383,17 +383,17 @@ Assuming you've already cloned the repository and set up your identity:
383
383
<!-- run-disable -->
384
384
385
385
```bash
386
-
git checkout develop
387
-
git pull --ff-only upstream develop
388
-
git push origin develop # Optional: Update your fork
386
+
$ git checkout develop
387
+
$ git pull --ff-only upstream develop
388
+
$ git push origin develop # Optional: Update your fork
389
389
```
390
390
391
391
2. **Create a new branch**:
392
392
393
393
<!-- run-disable -->
394
394
395
395
```bash
396
-
git checkout -b feature/is-even
396
+
$ git checkout -b feature/is-even
397
397
```
398
398
399
399
3. **Make changes**: This could involve adding the new function, writing tests, benchmarks, examples, updating documentation, etc.
@@ -403,17 +403,17 @@ Assuming you've already cloned the repository and set up your identity:
403
403
<!-- run-disable -->
404
404
405
405
```bash
406
-
git status # Optional: Check what's modified
407
-
git add .
408
-
git commit -m "feat: add isEven function"
406
+
$ git status # Optional: Check what's modified
407
+
$ git add .
408
+
$ git commit -m "feat: add isEven function"
409
409
```
410
410
411
411
If you prefer a multi-line commit message, use:
412
412
413
413
<!-- run-disable -->
414
414
415
415
```bash
416
-
git commit
416
+
$ git commit
417
417
```
418
418
419
419
Then write your message like:
@@ -431,7 +431,7 @@ Assuming you've already cloned the repository and set up your identity:
431
431
<!-- run-disable -->
432
432
433
433
```bash
434
-
git push --set-upstream origin feature/is-even
434
+
$ git push --set-upstream origin feature/is-even
435
435
```
436
436
437
437
> **Note:** As mentioned earlier, this is a one-time setup for this branch. After this, you can simply use `git push` for future updates.
@@ -443,34 +443,34 @@ Assuming you've already cloned the repository and set up your identity:
443
443
<!-- run-disable -->
444
444
445
445
```bash
446
-
git pull origin feature/is-even # git pull also works
446
+
$ git pull origin feature/is-even # git pull also works
447
447
```
448
448
449
449
Additionally, if new changes are added to the [upstream][git-remotes] `develop` branch, you can integrate them into your feature branch using rebase or merge:
450
450
451
451
<!-- run-disable -->
452
452
453
453
```bash
454
-
git checkout develop
455
-
git pull --ff-only upstream develop # Update local develop first
456
-
git checkout feature/is-even
457
-
git rebase develop # or git merge develop
454
+
$ git checkout develop
455
+
$ git pull --ff-only upstream develop # Update local develop first
456
+
$ git checkout feature/is-even
457
+
$ git rebase develop # or git merge develop
458
458
```
459
459
460
460
Resolve any conflicts with the steps mentioned earlier, then continue the rebase:
461
461
462
462
<!-- run-disable -->
463
463
464
464
```bash
465
-
git rebase --continue
465
+
$ git rebase --continue
466
466
```
467
467
468
468
Finally, push your changes:
469
469
470
470
<!-- run-disable -->
471
471
472
472
```bash
473
-
git push --force # Force push after rebasing
473
+
$ git push --force # Force push after rebasing
474
474
```
475
475
476
476
> **Note:** Force pushing is required after rebasing because it rewrites history. This is safe as long as you're the only one working on the branch. If you want to avoid force pushing, use merge instead of rebase.
0 commit comments