Skip to content

docs: update readme contributing guide #418

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jbampton merged 4 commits into from
Apr 4, 2026
Merged

docs: update readme contributing guide #418

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ffae5fb
docs: update README contributing guide with feature branch workflow a…
Copilot Apr 4, 2026
3d9aa3d
docs: clarify feature branch name placeholder in contributing steps
Copilot Apr 4, 2026
48e8ba1
docs: rename branch example from add-your-github-username to my-featu…
Copilot Apr 4, 2026
59aa925
Merge branch 'main' into copilot/update-readme-contributing-guide
jbampton Apr 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
262 changes: 250 additions & 12 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@
- [How to Add Yourself](#-how-to-add-yourself)
- [YAML File Format](#-yaml-file-format)
- [Local Development](#-local-development-optional)
- [Git Workflow & Keeping in Sync](#-git-workflow--keeping-in-sync)
- [Contribution Guidelines](#-contribution-guidelines)
- [Troubleshooting](#-troubleshooting--faq)
- [License](#-license)
Expand Down Expand Up @@ -68,23 +69,46 @@ Adding yourself to the directory is simple! Just follow these steps:
1. Click the **"Fork"** button at the top-right of this repository
2. This creates a copy of the repository under your GitHub account

### Step 2: Clone Your Fork
### Step 2: Clone Your Fork and Set Up Upstream

```bash
# Clone your fork
git clone https://github.com/YOUR-USERNAME/NextCommunity.github.io.git
cd NextCommunity.github.io

# Add the original repo as "upstream" so you can sync future changes
git remote add upstream https://github.com/NextCommunity/NextCommunity.github.io.git

# Verify your remotes (you should see both origin and upstream)
git remote -v
```

Replace `YOUR-USERNAME` with your actual GitHub username.

### Step 3: Create Your Profile File
### Step 3: Create a Feature Branch

**Never commit directly to `main`.** Always work on a dedicated feature branch:

```bash
# Make sure your local main is up to date first
git checkout main
git pull upstream main

# Create and switch to a new feature branch
git checkout -b my-feature-branch
```

Use a descriptive branch name that reflects your change, e.g. `add-jbampton` or `fix-yaml-typo`.
Replace `your-github-username` in every example below with the actual branch name you chose here.

### Step 4: Create Your Profile File

1. Navigate to the `src/users/` directory
2. Create a new file named `your-github-username.yaml`
- **Important**: Use your actual GitHub username in lowercase
- Example: If your GitHub username is `JohnDoe`, create `johndoe.yaml`

### Step 4: Fill In Your Details
### Step 5: Fill In Your Details

Copy the template below and customize it with your information:

Expand All @@ -110,7 +134,7 @@ bio: |

> 💡 **Tip**: Check out existing files in `src/users/` for real examples!

### Step 5: Test Locally (Optional but Recommended)
### Step 6: Test Locally (Optional but Recommended)

```bash
# Install dependencies
Expand All @@ -122,7 +146,7 @@ npm start

Visit `http://localhost:8080` to preview your profile before submitting.

### Step 6: Commit Your Changes
### Step 7: Commit Your Changes

```bash
# Add your new file
Expand All @@ -131,26 +155,28 @@ git add src/users/your-github-username.yaml
# Commit with a descriptive message
git commit -m "Add [Your Name] to developer directory"

# Push to your fork
git push origin main
# Push your feature branch to your fork (NOT main!)
# Replace 'my-feature-branch' with the branch name you created in Step 3
git push origin my-feature-branch
```

### Step 7: Create a Pull Request
### Step 8: Create a Pull Request

1. Go to your forked repository on GitHub
2. Click the **"Contribute"** button, then **"Open Pull Request"**
3. Write a clear title: `Add [Your Name] to directory`
4. In the description, mention:
3. Make sure the **base** branch is `main` on `NextCommunity/NextCommunity.github.io` and the **compare** branch is your feature branch
4. Write a clear title: `Add [Your Name] to directory`
5. In the description, mention:

```markdown
Fixes #213

Adding my profile to the NextCommunity developer directory.
```

5. Click **"Create Pull Request"**
6. Click **"Create Pull Request"**

### Step 8: Wait for Review ⏳
### Step 9: Wait for Review ⏳

- The maintainers will review your PR
- Automated checks will verify your YAML file
Expand Down Expand Up @@ -317,6 +343,218 @@ NextCommunity.github.io/

---

## 🔀 Git Workflow & Keeping in Sync

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.

### The Golden Rules

> 🚫 **Never push directly to `main`** in your fork.
> ✅ **Always work on a feature branch** and open a Pull Request.

---

### 🛠️ Essential Git Commands for Contributors

---

#### 1. `git remote` — Manage your remote connections

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.

```bash
# View all configured remotes
git remote -v

# Add the upstream remote (do this once, right after cloning)
git remote add upstream https://github.com/NextCommunity/NextCommunity.github.io.git

# After running the above, git remote -v should output:
# origin https://github.com/YOUR-USERNAME/NextCommunity.github.io.git (fetch)
# origin https://github.com/YOUR-USERNAME/NextCommunity.github.io.git (push)
# upstream https://github.com/NextCommunity/NextCommunity.github.io.git (fetch)
# upstream https://github.com/NextCommunity/NextCommunity.github.io.git (push)
```

---

#### 2. `git fetch` — Download changes without merging

`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.

```bash
# Fetch everything from the upstream repo
git fetch upstream

# Now you can inspect what changed without affecting your local branches
git log HEAD..upstream/main --oneline
```

---

#### 3. `git pull` — Fetch and integrate in one step

`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.

```bash
# Sync your local main with upstream/main
git checkout main
git pull upstream main

# Keep your fork's main in sync too (pushes updated main to your fork on GitHub)
git push origin main
```

> 💡 **Tip**: Run this before creating every new feature branch so you always start from the latest code.

---

#### 4. `git checkout -b` — Create and switch to a feature branch

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.

```bash
# Create a new branch and switch to it
git checkout -b my-feature-branch

# List all local branches (the active branch is marked with *)
git branch

# Switch between existing branches
git checkout main
git checkout my-feature-branch
```

Branch naming conventions used in this project:

| Prefix | When to use | Example |
|---|---|---|
| `add-` | Adding a new profile | `add-jbampton` |
| `fix-` | Fixing a bug or typo | `fix-yaml-typo` |
| `feat-` | Adding a new site feature | `feat-dark-mode` |
| `docs-` | Documentation changes | `docs-contributing-guide` |

---

#### 5. `git rebase` — Replay your commits on top of the latest upstream

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.

```bash
# First, fetch the latest upstream changes
git fetch upstream

# Rebase your feature branch on top of upstream/main
git checkout my-feature-branch
git rebase upstream/main
```

If conflicts arise during a rebase:

```bash
# 1. Open the conflicting file(s), resolve the conflict markers (<<<<, ====, >>>>)
# 2. Stage the resolved file(s)
git add src/users/your-github-username.yaml

# 3. Continue the rebase
git rebase --continue

# If you want to abort and go back to before the rebase started
git rebase --abort
```

After rebasing, you'll need to force-push your feature branch because the commit history was rewritten:

```bash
# Force push — only safe on your own feature branch, NEVER on main
git push origin my-feature-branch --force-with-lease
```

> ⚠️ `--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.

---

#### 6. `git stash` — Save work-in-progress without committing

If you need to switch branches but aren't ready to commit your changes, `git stash` temporarily shelves them.

```bash
# Save all uncommitted changes
git stash

# Switch to another branch, do some work, then come back
git checkout main
git pull upstream main
git checkout my-feature-branch

# Restore your stashed changes
git stash pop

# View all stashes
git stash list

# Apply a specific stash without removing it from the stash list
git stash apply stash@{0}
```

---

#### 7. `git log` — Explore commit history

`git log` lets you understand what has changed and when. It's invaluable for debugging and understanding the project timeline.

```bash
# View the last 10 commits in a compact format
git log --oneline -10

# See a visual branch graph
git log --oneline --graph --decorate --all

# See all commits by a specific author
git log --author="Your Name" --oneline

# See what changed in the last commit
git log -1 --stat
```

---

### 🔄 Full Day-to-Day Sync Workflow

Here's the complete workflow to follow every time you start a new contribution:

```bash
# 1. Switch to main and pull the latest upstream changes
git checkout main
git fetch upstream
git merge upstream/main # or: git pull upstream main

# 2. Push the updated main to your fork so GitHub is also up to date
git push origin main

# 3. Create a new feature branch from the freshly synced main
git checkout -b my-feature-branch

# 4. Make your changes, then stage and commit them
git add src/users/your-github-username.yaml
git commit -m "Add [Your Name] to developer directory"

# 5. Push your feature branch to your fork on GitHub
git push origin my-feature-branch

# 6. Open a Pull Request on GitHub from your feature branch → NextCommunity/main
```

If your feature branch gets out of date while you're working on it (because `main` received new commits), sync it with rebase:

```bash
git fetch upstream
git rebase upstream/main
git push origin my-feature-branch --force-with-lease
```

---

## 🤝 Contribution Guidelines

### Code of Conduct
Expand Down
Loading