diff --git a/README.md b/README.md index 8a8b1b9..54e7d0f 100644 --- a/README.md +++ b/README.md @@ -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) @@ -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: @@ -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 @@ -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 @@ -131,16 +155,18 @@ 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 @@ -148,9 +174,9 @@ git push origin main 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 @@ -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