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
git commit -m "Add [Your Name] to developer directory"
133
156
134
-
# Push to your fork
135
-
git push origin main
157
+
# Push your feature branch to your fork (NOT main!)
158
+
git push origin add-your-github-username
136
159
```
137
160
138
-
### Step 7: Create a Pull Request
161
+
### Step 8: Create a Pull Request
139
162
140
163
1. Go to your forked repository on GitHub
141
164
2. Click the **"Contribute"** button, then **"Open Pull Request"**
142
-
3. Write a clear title: `Add [Your Name] to directory`
143
-
4. In the description, mention:
165
+
3. Make sure the **base** branch is `main` on `NextCommunity/NextCommunity.github.io` and the **compare** branch is your feature branch
166
+
4. Write a clear title: `Add [Your Name] to directory`
167
+
5. In the description, mention:
144
168
145
169
```markdown
146
170
Fixes #213
147
171
148
172
Adding my profile to the NextCommunity developer directory.
149
173
```
150
174
151
-
5. Click **"Create Pull Request"**
175
+
6. Click **"Create Pull Request"**
152
176
153
-
### Step 8: Wait for Review ⏳
177
+
### Step 9: Wait for Review ⏳
154
178
155
179
- The maintainers will review your PR
156
180
- Automated checks will verify your YAML file
@@ -317,6 +341,218 @@ NextCommunity.github.io/
317
341
318
342
---
319
343
344
+
## 🔀 Git Workflow & Keeping in Sync
345
+
346
+
Working with a forked repository means your copy can fall behind the upstream (the original NextCommunity repo) over time. This section explains the complete feature-branch workflow and the essential git commands every contributor should know.
347
+
348
+
### The Golden Rules
349
+
350
+
> 🚫 **Never push directly to `main`** in your fork.
351
+
> ✅ **Always work on a feature branch** and open a Pull Request.
352
+
353
+
---
354
+
355
+
### 🛠️ Essential Git Commands for Contributors
356
+
357
+
---
358
+
359
+
#### 1. `git remote` — Manage your remote connections
360
+
361
+
Your fork is connected to your own GitHub account (`origin`). To stay in sync with the original project, you also need a connection to the upstream repo.
362
+
363
+
```bash
364
+
# View all configured remotes
365
+
git remote -v
366
+
367
+
# Add the upstream remote (do this once, right after cloning)
#### 2. `git fetch` — Download changes without merging
380
+
381
+
`git fetch`downloads new commits and branches from a remote but does **not** touch your working files. It's a safe way to inspect what's changed upstream before deciding what to do.
382
+
383
+
```bash
384
+
# Fetch everything from the upstream repo
385
+
git fetch upstream
386
+
387
+
# Now you can inspect what changed without affecting your local branches
388
+
git log HEAD..upstream/main --oneline
389
+
```
390
+
391
+
---
392
+
393
+
#### 3. `git pull` — Fetch and integrate in one step
394
+
395
+
`git pull`is shorthand for `git fetch` followed by `git merge` (or `git rebase`, depending on your config). Use it to bring your local branch up to date.
396
+
397
+
```bash
398
+
# Sync your local main with upstream/main
399
+
git checkout main
400
+
git pull upstream main
401
+
402
+
# Keep your fork's main in sync too (pushes updated main to your fork on GitHub)
403
+
git push origin main
404
+
```
405
+
406
+
> 💡 **Tip**: Run this before creating every new feature branch so you always start from the latest code.
407
+
408
+
---
409
+
410
+
#### 4. `git checkout -b` — Create and switch to a feature branch
411
+
412
+
A feature branch isolates your work so that `main` stays clean and ready to sync. The `-b` flag creates the branch and switches to it in one command.
413
+
414
+
```bash
415
+
# Create a new branch and switch to it
416
+
git checkout -b add-your-github-username
417
+
418
+
# List all local branches (the active branch is marked with *)
419
+
git branch
420
+
421
+
# Switch between existing branches
422
+
git checkout main
423
+
git checkout add-your-github-username
424
+
```
425
+
426
+
Branch naming conventions used in this project:
427
+
428
+
| Prefix | When to use | Example |
429
+
|---|---|---|
430
+
| `add-` | Adding a new profile | `add-jbampton` |
431
+
| `fix-` | Fixing a bug or typo | `fix-yaml-typo` |
432
+
| `feat-` | Adding a new site feature | `feat-dark-mode` |
#### 5. `git rebase` — Replay your commits on top of the latest upstream
438
+
439
+
When `main` has moved forward since you created your branch, `git rebase` re-applies your commits on top of the latest changes instead of creating a messy merge commit. This keeps the project history clean and linear.
440
+
441
+
```bash
442
+
# First, fetch the latest upstream changes
443
+
git fetch upstream
444
+
445
+
# Rebase your feature branch on top of upstream/main
446
+
git checkout add-your-github-username
447
+
git rebase upstream/main
448
+
```
449
+
450
+
If conflicts arise during a rebase:
451
+
452
+
```bash
453
+
# 1. Open the conflicting file(s), resolve the conflict markers (<<<<, ====, >>>>)
454
+
# 2. Stage the resolved file(s)
455
+
git add src/users/your-github-username.yaml
456
+
457
+
# 3. Continue the rebase
458
+
git rebase --continue
459
+
460
+
# If you want to abort and go back to before the rebase started
461
+
git rebase --abort
462
+
```
463
+
464
+
After rebasing, you'll need to force-push your feature branch because the commit history was rewritten:
465
+
466
+
```bash
467
+
# Force push — only safe on your own feature branch, NEVER on main
> ⚠️ `--force-with-lease` is safer than `--force`: it fails if someone else has pushed to your branch since you last fetched, preventing accidental data loss.
472
+
473
+
---
474
+
475
+
#### 6. `git stash` — Save work-in-progress without committing
476
+
477
+
If you need to switch branches but aren't ready to commit your changes, `git stash` temporarily shelves them.
478
+
479
+
```bash
480
+
# Save all uncommitted changes
481
+
git stash
482
+
483
+
# Switch to another branch, do some work, then come back
484
+
git checkout main
485
+
git pull upstream main
486
+
git checkout add-your-github-username
487
+
488
+
# Restore your stashed changes
489
+
git stash pop
490
+
491
+
# View all stashes
492
+
git stash list
493
+
494
+
# Apply a specific stash without removing it from the stash list
495
+
git stash apply stash@{0}
496
+
```
497
+
498
+
---
499
+
500
+
#### 7. `git log` — Explore commit history
501
+
502
+
`git log`lets you understand what has changed and when. It's invaluable for debugging and understanding the project timeline.
503
+
504
+
```bash
505
+
# View the last 10 commits in a compact format
506
+
git log --oneline -10
507
+
508
+
# See a visual branch graph
509
+
git log --oneline --graph --decorate --all
510
+
511
+
# See all commits by a specific author
512
+
git log --author="Your Name" --oneline
513
+
514
+
# See what changed in the last commit
515
+
git log -1 --stat
516
+
```
517
+
518
+
---
519
+
520
+
### 🔄 Full Day-to-Day Sync Workflow
521
+
522
+
Here's the complete workflow to follow every time you start a new contribution:
523
+
524
+
```bash
525
+
# 1. Switch to main and pull the latest upstream changes
526
+
git checkout main
527
+
git fetch upstream
528
+
git merge upstream/main # or: git pull upstream main
529
+
530
+
# 2. Push the updated main to your fork so GitHub is also up to date
531
+
git push origin main
532
+
533
+
# 3. Create a new feature branch from the freshly synced main
534
+
git checkout -b add-your-github-username
535
+
536
+
# 4. Make your changes, then stage and commit them
537
+
git add src/users/your-github-username.yaml
538
+
git commit -m "Add [Your Name] to developer directory"
539
+
540
+
# 5. Push your feature branch to your fork on GitHub
541
+
git push origin add-your-github-username
542
+
543
+
# 6. Open a Pull Request on GitHub from your feature branch → NextCommunity/main
544
+
```
545
+
546
+
If your feature branch gets out of date while you're working on it (because `main` received new commits), sync it with rebase:
0 commit comments