Skip to content

Commit 818e90e

Browse files
anandkaranubcanandkaranubc
committed
docs: add a section for conflicts and example workflow
--- type: pre_commit_static_analysis_report description: Results of running static analysis checks when committing changes. report: - task: lint_filenames status: passed - task: lint_editorconfig status: passed - task: lint_markdown status: passed - task: lint_package_json status: na - task: lint_repl_help status: na - task: lint_javascript_src status: na - task: lint_javascript_cli status: na - task: lint_javascript_examples status: na - task: lint_javascript_tests status: na - task: lint_javascript_benchmarks status: na - task: lint_python status: na - task: lint_r status: na - task: lint_c_src status: na - task: lint_c_examples status: na - task: lint_c_benchmarks status: na - task: lint_c_tests_fixtures status: na - task: lint_shell status: na - task: lint_typescript_declarations status: na - task: lint_typescript_tests status: na - task: lint_license_headers status: passed --- --- type: pre_push_report description: Results of running various checks prior to pushing changes. report: - task: run_javascript_examples status: na - task: run_c_examples status: na - task: run_cpp_examples status: na - task: run_javascript_readme_examples status: na - task: run_c_benchmarks status: na - task: run_cpp_benchmarks status: na - task: run_fortran_benchmarks status: na - task: run_javascript_benchmarks status: na - task: run_julia_benchmarks status: na - task: run_python_benchmarks status: na - task: run_r_benchmarks status: na - task: run_javascript_tests status: na ---
1 parent c22efc3 commit 818e90e

File tree

1 file changed

+202
-4
lines changed

1 file changed

+202
-4
lines changed

‎docs/contributing/git_cheatsheet.md‎

Lines changed: 202 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@ git remote add upstream https://github.com/stdlib-js/stdlib.git
7272
git fetch upstream
7373
```
7474

75-
> 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 remote allows you to consistently fetch the latest updates from the original repository and incorporate them into your work.
75+
> 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.
7676
7777
## Branching
7878

@@ -111,6 +111,40 @@ Then, commit with a meaningful message:
111111
git commit -m "feat: add support for new function"
112112
```
113113

114+
For **multi-line** commit messages (like when you want to include a longer description), you can use:
115+
116+
<!-- run-disable -->
117+
118+
```bash
119+
git commit
120+
```
121+
122+
This opens an editor where you can write something like:
123+
124+
```bash
125+
feat: add support for new function
126+
127+
This adds the initial version of <function_name>, with support for <brief explanation>.
128+
```
129+
130+
**After writing your message:**
131+
132+
- **Vim**: press `Esc`, type `:wq`, then press `Enter`
133+
- **Nano**: `Ctrl+O`, then `Enter`, then `Ctrl+X`
134+
- **VS Code**: save and close the editor
135+
136+
> Multi-line commits are especially useful for giving extra context on why the change was made, or summarizing multiple related changes.
137+
138+
To make this even easier, you can also use:
139+
140+
<!-- run-disable -->
141+
142+
```bash
143+
make commit
144+
```
145+
146+
This gives you an interactive prompt to help you craft a properly formatted commit message. Super handy!
147+
114148
Try to keep your commit messages clear and concise! Adhering to stdlib's [Git Style Guide][github-style-guide] ensures a well-structured and understandable commit history.
115149

116150
## Pushing
@@ -123,7 +157,7 @@ Once your branch is ready, you need to push your **local** changes to your forke
123157
git push
124158
```
125159

126-
If this is the first time you’re pushing the branch, [Git][git] may prompt you to set an upstream 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:
127161

128162
<!-- run-disable -->
129163

@@ -158,8 +192,7 @@ git checkout develop
158192
git pull --ff-only upstream develop
159193
```
160194

161-
> **Why use `--ff-only`?**
162-
> 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.
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.
163196
164197
If the above pull fails because you accidentally made changes to `develop`, you can **reset** it to match the official repository:
165198

@@ -279,6 +312,171 @@ Use **Merge** if:
279312

280313
> **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.
281314
315+
## Merge Conflicts
316+
317+
Merge conflicts occur when Git can't automatically resolve differences between two commits (e.g., your branch and `develop`). This usually happens when you rebase or merge branches with conflicting changes. This is how a conflict looks in a file:
318+
319+
```plaintext
320+
function isEven(x) {
321+
<<<<<<< HEAD
322+
return ( x % 2 ) === 0;
323+
=======
324+
return ( x & 1 ) === 0;
325+
>>>>>>> feature/bitwise-check
326+
}
327+
```
328+
329+
> Note: The `HEAD` section represents your current branch (`feature/bitwise-check`), while the `incoming` section represents the branch you're merging or rebasing (e.g., `develop`).
330+
331+
To resolve a merge conflict:
332+
333+
- Open the file in your editor.
334+
- Choose which changes to keep.
335+
- Remove the conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`).
336+
- Save the file.
337+
- Add the file to the staging area.
338+
- Continue the rebase or merge process.
339+
340+
### Example
341+
342+
We will consider the conflict in the `isEven` function above. Let's say you want to keep your changes and use the bitwise AND operator (`&`) instead of the modulo operator (`%`). Here's how you can resolve the conflict:
343+
344+
- Modify the file to look like this:
345+
346+
```plaintext
347+
function isEven(x) {
348+
return ( x & 1 ) === 0;
349+
}
350+
```
351+
352+
- Add the file to the staging area:
353+
354+
<!-- run-disable -->
355+
356+
```bash
357+
git add <file>
358+
```
359+
360+
- Continue the rebase or merge:
361+
362+
<!-- run-disable -->
363+
364+
```bash
365+
git rebase --continue # If rebasing
366+
git merge --continue # If merging
367+
```
368+
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.
370+
371+
Merge conflicts can be annoying, but they’re a natural part of working with others. Take your time, and don’t hesitate to ask for help if you're stuck.
372+
373+
## Example Workflow
374+
375+
Now that you have all the essential commands, let's put them together in a typical workflow:
376+
377+
**Goal**: Add a new function `isEven` to `stdlib`.
378+
379+
Assuming you've already cloned the repository and set up your identity:
380+
381+
1. **Sync `develop`**:
382+
383+
<!-- run-disable -->
384+
385+
```bash
386+
git checkout develop
387+
git pull --ff-only upstream develop
388+
git push origin develop # Optional: Update your fork
389+
```
390+
391+
2. **Create a new branch**:
392+
393+
<!-- run-disable -->
394+
395+
```bash
396+
git checkout -b feature/is-even
397+
```
398+
399+
3. **Make changes**: This could involve adding the new function, writing tests, benchmarks, examples, updating documentation, etc.
400+
401+
4. **Commit your changes**:
402+
403+
<!-- run-disable -->
404+
405+
```bash
406+
git status # Optional: Check what's modified
407+
git add .
408+
git commit -m "feat: add isEven function"
409+
```
410+
411+
If you prefer a multi-line commit message, use:
412+
413+
<!-- run-disable -->
414+
415+
```bash
416+
git commit
417+
```
418+
419+
Then write your message like:
420+
421+
```plaintext
422+
feat: add isEven function
423+
424+
This adds the complete implementation of the isEven function, along with benchmarks, examples, tests, and documentation. The implementation is based on the modulo operator.
425+
```
426+
427+
Save and close the editor. As mentioned earlier, you can also use `make commit` for an interactive prompt.
428+
429+
5. **Push your branch**:
430+
431+
<!-- run-disable -->
432+
433+
```bash
434+
git push --set-upstream origin feature/is-even
435+
```
436+
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.
438+
439+
6. **Create a pull request**: Go to your fork on GitHub, click "Compare & pull request", add a title and description, and create the PR.
440+
441+
7. **Review and update**: If you or the reviewers make changes to your PR through the GitHub UI, you need to update your local branch with those changes:
442+
443+
<!-- run-disable -->
444+
445+
```bash
446+
git pull origin feature/is-even # git pull also works
447+
```
448+
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+
451+
<!-- run-disable -->
452+
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
458+
```
459+
460+
Resolve any conflicts with the steps mentioned earlier, then continue the rebase:
461+
462+
<!-- run-disable -->
463+
464+
```bash
465+
git rebase --continue
466+
```
467+
468+
Finally, push your changes:
469+
470+
<!-- run-disable -->
471+
472+
```bash
473+
git push --force # Force push after rebasing
474+
```
475+
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.
477+
478+
8. **Repeat**: After resolving conflicts and updating your branch, you can continue making changes, committing, and pushing until your PR is ready to be merged.
479+
282480
## Conclusion
283481
284482
Congratulations! You now have all the essential Git commands to navigate your workflow smoothly while contributing to `stdlib`. Whether you're fixing a bug, adding a feature, or just getting started, this cheatsheet will help you stay organized and avoid common pitfalls. Keep practicing, stay curious, and enjoy the process. Happy coding!

0 commit comments

Comments
 (0)