Saltar al contenido principal

GitHub Instructions for DILVE Help Project

📋 Table of Contents​

Initial Setup (One-time)​

Step 1: Create Repository on GitHub​

  1. Go to github.com
  2. Log in with your paid account
  3. Click the "+" button (top right) → "New repository"
  4. Fill in:
    • Repository name: dilvehelp (or your preferred name)
    • Description: "DILVE Help Documentation - Docusaurus"
    • Visibility: Choose Private (for team only) or Public
    • DO NOT check "Initialize with README" (you already have a project)
  5. Click "Create repository"
  6. Copy the repository URL shown (looks like: https://github.com/YOUR-USERNAME/dilvehelp.git)

Step 2: Connect Your Local Project to GitHub​

Open PowerShell or Terminal in your project folder (E:\Google_Drive\dilve21\help\dilvehelp) and run:

# Add the remote repository (replace with YOUR URL from Step 1)
git remote add origin https://github.com/YOUR-USERNAME/dilvehelp.git

# Verify it was added
git remote -v

# Push your code to GitHub for the first time
git push -u origin main

Note: If you get an error about main vs master, first check your branch name:

git branch
# If it shows "master" instead of "main", use:
git push -u origin master

Step 3: Invite Team Members​

  1. On GitHub, go to your repository
  2. Click "Settings" tab
  3. Click "Collaborators" (left sidebar)
  4. Click "Add people"
  5. Enter team member's GitHub username or email
  6. Choose permission level:
    • Write: Can push changes (recommended for active developers)
    • Read: Can only view and clone (for reviewers)

Daily Workflow​

🔄 Basic Cycle: Pull → Work → Commit → Push​

# 1. ALWAYS start by getting latest changes from GitHub
git pull

# 2. Work on your files normally in VS Code

# 3. Check what files you changed
git status

# 4. Add files to commit (choose one method):
git add .                           # Add all changed files
git add filename.md                 # Add specific file

# 5. Commit with a descriptive message
git commit -m "Added new section on forms"

# 6. Push to GitHub
git push

📝 Making Good Commit Messages​

✅ Good examples:

  • "Added BackButton component to pantallas pages"
  • "Fixed broken links in mi-catalogo section"
  • "Updated sidebar with new Pantallas menu"

❌ Bad examples:

  • "changes", "update", "fix" (too vague)

Team Collaboration​

For Team Members: First Time Setup​

  1. Install Git (if not already installed):

    • Windows: Download from git-scm.com
    • Verify: Open PowerShell and type git --version

  2. Configure Git (one-time):

    git config --global user.name "Your Name"
    git config --global user.email "your.email@example.com"

  3. Clone the repository:

    # Navigate to where you want the project
    cd C:\Projects

    # Clone (use the URL from GitHub)
    git clone https://github.com/YOUR-USERNAME/dilvehelp.git

    # Enter the project folder
    cd dilvehelp

    # Install dependencies
    npm install

Working Together: Avoiding Conflicts​

Rule #1: Always git pull before starting work Rule #2: Commit and push frequently (at least daily) Rule #3: Don't work on the same file simultaneously

If Multiple People Edit Different Files:​

git pull      # Gets everyone else's changes
git push      # Sends your changes
# Usually works smoothly! ✅

If You Get a "Conflict" Error:​

# 1. Pull changes
git pull

# 2. Git will mark conflicts in files like this:
<<<<<<< HEAD
Your changes
=======
Someone else's changes
>>>>>>> origin/main

# 3. Open the file in VS Code
# 4. Choose which version to keep (or combine them)
# 5. Delete the <<<, ===, >>> markers
# 6. Save the file

# 7. Mark as resolved and push:
git add filename.md
git commit -m "Resolved conflict in filename.md"
git push

Common Scenarios​

Scenario 1: See What Changed Before Committing​

git status              # List changed files
git diff                # Show detailed changes
git diff filename.md    # Show changes in specific file

Scenario 2: Undo Uncommitted Changes​

# Undo changes to a specific file
git checkout -- filename.md

# Undo all uncommitted changes (careful!)
git checkout -- .

Scenario 3: View Commit History​

git log                 # Full history
git log --oneline       # Compact view
git log --oneline -10   # Last 10 commits

Scenario 4: See What Someone Else Changed​

# Pull their changes
git pull

# See what was changed
git log --oneline -5
git show commit-hash    # Use hash from log

Scenario 5: Work on a Feature Without Affecting Main Code​

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

# Work normally, commit changes
git add .
git commit -m "Working on new feature"

# Push the branch to GitHub
git push -u origin feature-name

# When ready, merge back to main:
git checkout main
git merge feature-name
git push

Troubleshooting​

Problem: "Permission denied" or "Authentication failed"​

Solution: Set up authentication with GitHub

Option A - HTTPS with Personal Access Token (Recommended):

  1. Go to GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
  2. Generate new token (give it repo permissions)
  3. Copy the token
  4. When prompted for password during git push, use the token instead

Option B - SSH Keys: Follow GitHub's SSH guide

Problem: "fatal: refusing to merge unrelated histories"​

git pull origin main --allow-unrelated-histories

Problem: Forgot to pull before making changes​

# Save your changes temporarily
git stash

# Get latest changes
git pull

# Apply your changes back
git stash pop

Problem: Want to see changes visually​

Use VS Code's built-in Git features:

  • Click the Source Control icon (left sidebar)
  • View changed files
  • Click any file to see side-by-side diff
  • Use the Timeline view (bottom of Explorer) to see file history

Quick Reference Commands​

CommandWhat it does
git statusSee what files changed
git pullGet latest changes from GitHub
git add .Stage all changes
git add filenameStage specific file
git commit -m "message"Save changes with message
git pushSend changes to GitHub
git log --onelineView commit history
git diffSee what changed
git branchSee current branch
git checkout -b nameCreate new branch

Daily Checklist​

✅ Start of work:

  1. git pull - Get latest changes
  2. Work on files
  3. Test your changes (npm run start)

✅ End of work:

  1. git status - Check what changed
  2. git add . - Stage changes
  3. git commit -m "Descriptive message"
  4. git push - Share with team

Getting Help​

  • In VS Code: Press Ctrl+Shift+P → type "Git" to see all Git commands
  • GitHub Docs: docs.github.com
  • Team Lead: [Add contact info]

Team Workflow Strategy​

Overview​

For a small 3-person team working on documentation, use this flexible approach:

  • Simple changes: Work directly on main branch
  • Major changes: Use feature branches
  • Always communicate what you're working on

Daily Work (Simple Changes)​

Work directly on main branch for small edits, typos, and minor updates:

git pull              # Always start with this!
# Make your changes
git add .
git commit -m "Updated X section"
git push

When to use:

  • Fixing typos
  • Adding content to existing pages
  • Small corrections
  • Updates to existing documentation

Bigger Features (New Sections, Major Changes)​

Use feature branches for significant work:

# 1. Create and switch to a new branch
git checkout -b feature/new-pantallas-section

# 2. Work normally
# Edit files, save changes

# 3. Commit to your branch
git add .
git commit -m "Added new pantallas section"

# 4. Push your branch to GitHub
git push -u origin feature/new-pantallas-section

# 5. When ready, merge back to main
git checkout main
git pull                    # Get latest main
git merge feature/new-pantallas-section
git push

# 6. Delete the branch (cleanup)
git branch -d feature/new-pantallas-section
git push origin --delete feature/new-pantallas-section

When to use:

  • New major sections
  • Restructuring content
  • Experimental changes
  • Work that takes more than a few hours

Branch Naming Conventions​

Use descriptive names with prefixes:

feature/name      - New features (e.g., feature/github-guide)
fix/name          - Bug fixes (e.g., fix/broken-links)
update/name       - Updates to existing content (e.g., update/sidebar)
docs/name         - Documentation changes (e.g., docs/api-reference)

Team Workflow Rules​

Rule #1: Communication​

Before starting work, communicate:

  • Post in team chat: "I'm working on the Forms section"
  • Update the team: "Updating the sidebar structure"

This prevents conflicts and duplicate work!

Rule #2: Pull Before Push​

Always pull before pushing:

git pull    # Do this BEFORE git push

This gets the latest changes from your teammates.

Rule #3: Commit Often, Push Daily​

# End of each work session:
git add .
git commit -m "Descriptive message"
git push

Don't keep changes local overnight!

Common Team Scenarios​

Scenario 1: Two People Editing Different Files ✅​

# Person A: edits file1.md
git pull
# edit file1.md
git add .
git commit -m "Updated file1"
git push

# Person B: edits file2.md
git pull              # Gets Person A's changes
# edit file2.md
git add .
git commit -m "Updated file2"
git push              # No conflict!

Result: Works perfectly! No conflicts.

Scenario 2: Two People Editing Same File 🟡​

# Person A: pushes first
git push              # Success!

# Person B: tries to push
git push              # ERROR: Updates were rejected

# Person B must pull first:
git pull              # Might auto-merge or show conflict

# If conflict occurs:
# 1. Open the file in VS Code
# 2. VS Code shows the conflict with buttons
# 3. Choose "Accept Current" or "Accept Incoming" or edit manually
# 4. Remove the conflict markers (<<<, ===, >>>)
# 5. Save the file
git add .
git commit -m "Resolved conflict in filename"
git push              # Now it works!

Result: Conflicts are manageable with VS Code's visual tools.

Using GitHub Pull Requests (Optional)​

For important changes requiring team review:

# 1. Create branch and make changes
git checkout -b feature/important-change
# ... make changes ...
git add .
git commit -m "Important changes"
git push -u origin feature/important-change

2. On GitHub.com:

  • Go to your repository
  • Click "Pull requests" → "New pull request"
  • Select your branch
  • Click "Create pull request"
  • Add description of changes
  • Request review from teammate

3. Teammate reviews:

  • Reads the changes
  • Adds comments or suggestions
  • Approves or requests changes

4. Merge the Pull Request:

  • Click "Merge pull request" on GitHub
  • Click "Confirm merge"
  • Delete the branch on GitHub

5. Everyone else updates:

git checkout main
git pull

Quick Decision Tree​

Is this a small fix or typo?
  └─ YES → Work on main: pull → edit → commit → push

Is this a major change or new section?
  └─ YES → Create feature branch → work → merge

Do you want team review before merging?
  └─ YES → Create branch → push → Pull Request on GitHub

Unsure if someone is working on same file?
  └─ Ask in team chat first!

Pro Tips for 3-Person Team​

  1. Daily standup (async): Post in team chat what you're working on today
  2. Keep branches short-lived: Don't work on a branch for more than 2-3 days
  3. Use descriptive commit messages: "Added pricing section" not "updates"
  4. Don't fear conflicts: They're easy to resolve in VS Code
  5. Push before leaving: Don't keep uncommitted changes overnight
  6. Review each other's work: Even informal reviews catch mistakes
  7. Document decisions: Add notes in commit messages about why you made changes

Emergency: "I Messed Up!"​

Undo uncommitted changes​

# Undo changes to a specific file
git checkout -- filename.md

# Undo ALL uncommitted changes (careful!)
git reset --hard

Undo last commit (keep changes)​

git reset --soft HEAD~1
# Your changes are still there, just uncommitted

Undo last commit (discard changes)​

git reset --hard HEAD~1
# Changes are permanently lost!

Get back a deleted file​

git checkout HEAD -- filename.md

Accidentally committed to wrong branch​

# On wrong branch, before pushing:
git reset --soft HEAD~1
git stash
git checkout correct-branch
git stash pop
git add .
git commit -m "Your message"

Need help from teammate​

  • They can check what's wrong on GitHub
  • Share your screen to troubleshoot together
  • Can always create a new branch from a previous commit

For your 3-person documentation team:

  • 80% of the time: Work directly on main with frequent pulls
  • 20% of the time: Use feature branches for big changes
  • Always: Communicate what you're working on

This keeps things simple but safe! 🎯

Viewing Team Activity​

See what others are doing:

# See recent commits by everyone
git log --oneline -10

# See who changed what in a file
git log --oneline -- filename.md

# See detailed changes in last commit
git show

# See what branch you're on
git branch

On GitHub.com:

  • Go to repository → "Commits" tab
  • See all recent changes by all team members
  • Click any commit to see what changed

Repository Information​

  • Repository URL: https://github.com/YOUR-USERNAME/dilvehelp
  • Main Branch: main (or master)
  • Project Type: Docusaurus Documentation Site
  • Build Command: npm run build
  • Dev Server: npm run start

Last Updated: January 25, 2026

Última actualización en por Jesus Peraita