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