본문으로 건너뛰기

GitHub Guide

How we use GitHub at Kyndof for version control, code collaboration, and technical project management.

GitHub is where Kyndof's code, technical specifications, and technical collaboration happen. This guide is for everyone—technical and non-technical team members alike.

What GitHub Is For​

GitHub is our version control and code collaboration platform, built on Git.

Use GitHub for:

  • Source code and version control
  • Technical specifications and architecture docs
  • Issue tracking for technical work
  • Code reviews and pull requests
  • Technical project boards
  • Architecture Decision Records (ADRs)
  • Infrastructure as code (deployment configs)

Don't use GitHub for:

  • Non-technical project management (use Notion)
  • Real-time chat (use Slack)
  • Large binary files (use Google Drive or S3)
  • Business documentation (use Notion or Wiki)
  • Sensitive credentials (use 1Password)

GitHub is optimized for code and text files that change over time and need version history.

GitHub Basics for Non-Technical Users​

You don't need to be an engineer to use GitHub. Here's what you need to know:

Key Concepts​

Repository (repo) - A project folder containing code and files

  • Think of it as a shared project folder
  • Everyone can see the files and their history
  • Changes are tracked over time

Commit - A saved snapshot of changes

  • Like "Save As" with a description of what changed
  • Creates permanent record in version history
  • Can always go back to previous commits

Branch - A parallel version of the code

  • Lets people work on features without affecting main code
  • Merged back to main when ready
  • Main branch is usually called main or master

Pull Request (PR) - A proposal to merge changes

  • "Please review these changes and merge if good"
  • Allows discussion and review before merging
  • Shows exactly what changed

Issue - A tracked task, bug, or discussion

  • Like a ticket or card in project management
  • Can be assigned to people
  • Can be linked to commits and PRs

Web Interface​

You can do most things through GitHub's web interface without using command line:

View files:

  1. Go to repository
  2. Click on folders and files to browse
  3. Click file name to see contents
  4. Click "History" to see changes over time

Edit files:

  1. Click file name
  2. Click pencil icon (Edit this file)
  3. Make changes in browser
  4. Scroll down, describe changes
  5. Click "Commit changes"

Create issues:

  1. Go to repository
  2. Click "Issues" tab
  3. Click "New issue"
  4. Fill in title and description
  5. Add labels, assignees, projects
  6. Click "Submit new issue"

Comment on PRs:

  1. Go to "Pull requests" tab
  2. Click PR title
  3. Review changes in "Files changed" tab
  4. Click line number to add comment
  5. Submit review (Approve, Request changes, or Comment)

Kyndof's GitHub Organization​

Kyndof's GitHub organization: github.com/kyndof

Repository Structure​

Our repositories are organized by purpose:

Product Repositories:

  • kyndof-os - Main operating system (CompanyOS)
  • runtime - Backend services and APIs
  • world-model - Knowledge graph and data models
  • wiki - Internal wiki (this site you're reading)

Service Repositories:

  • slack-bot - Nubabel Slack integration
  • notion-sync - Notion synchronization service
  • auth-service - Authentication and authorization

Infrastructure:

  • infrastructure - Terraform and deployment configs
  • docker-configs - Docker and container configs
  • ci-cd - CI/CD pipeline definitions

Archive:

  • Old or experimental repos (prefixed with archive-)

Naming Conventions​

Repository naming:

  • product-name - Product repositories
  • service-name - Backend services
  • tool-name - Internal tools
  • archive-name - Archived projects

Branch naming:

  • main - Primary branch (production-ready)
  • develop - Development branch (staging)
  • feature/feature-name - New features
  • fix/bug-name - Bug fixes
  • docs/topic - Documentation updates
  • refactor/area - Code refactoring

Commit message format:

type(scope): description

feat(auth): add OAuth2 support
fix(api): resolve race condition in user creation
docs(readme): update installation instructions
refactor(db): simplify query builder

Working with Repositories​

Cloning a Repository​

What it means: Download a copy to work on locally

How to clone:

  1. Go to repository page
  2. Click green "Code" button
  3. Copy HTTPS URL
  4. In terminal: git clone [URL]

Or use GitHub Desktop (easier for beginners):

  1. Download GitHub Desktop
  2. File → Clone repository
  3. Choose repository from list
  4. Pick local folder

Making Changes​

Direct web editing (small changes only):

  1. Navigate to file on GitHub.com
  2. Click pencil icon
  3. Edit in browser
  4. Commit with description

Local editing (recommended for larger work):

  1. Clone repository
  2. Create new branch: git checkout -b feature/my-feature
  3. Make changes in your editor
  4. Save files
  5. Commit changes: git add . then git commit -m "description"
  6. Push to GitHub: git push origin feature/my-feature
  7. Create pull request on GitHub

Understanding Diffs​

Diff shows what changed between versions:

  • Green lines with + - Added content
  • Red lines with - - Removed content
  • White lines - Unchanged context

Reading diffs:

  • Look at file name at top
  • Scroll through changes
  • Comments often explain why changes were made

Pull Requests (PRs)​

PRs are how code changes get reviewed and merged.

Creating a Pull Request​

  1. Push your branch to GitHub
  2. Go to repository on GitHub.com
  3. Click "Pull requests" tab
  4. Click "New pull request"
  5. Select your branch to merge into main
  6. Fill in PR template:
    • Title - Clear, concise description
    • Description - What changed and why
    • Linked issues - Reference related issues
    • Screenshots - For UI changes
    • Testing - How you verified it works
  7. Request reviewers
  8. Click "Create pull request"

PR Template (Kyndof Standard)​

## What Changed
Brief description of the changes

## Why
Reason for this change (business context, bug fix, etc.)

## How to Test
Steps to verify this works:
1. ...
2. ...

## Related
- Closes #123
- Related to #456

## Screenshots
(if applicable)

## Checklist
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] No breaking changes (or documented)

Reviewing Pull Requests​

Anyone can review PRs (not just engineers). Non-technical reviews are valuable for:

  • Documentation clarity
  • User experience
  • Business logic correctness
  • Copy and messaging

How to review:

  1. Open PR
  2. Read description
  3. Check "Files changed" tab
  4. Click line numbers to add comments
  5. Submit review:
    • Approve - Looks good, ready to merge
    • Request changes - Issues that must be fixed
    • Comment - Feedback without blocking

Good review feedback:

  • Be specific: "This error message is unclear" not "This is confusing"
  • Explain why: "Users won't understand 'auth token' – use 'login code' instead"
  • Ask questions: "Why did we choose this approach?"
  • Acknowledge good work: "Nice catch on that edge case"

Merging​

Who can merge:

  • PR author after approval from required reviewers
  • Repository maintainers

Merge strategies:

  • Squash and merge (preferred at Kyndof) - Combines commits into one
  • Merge commit - Keeps all commits, creates merge commit
  • Rebase and merge - Linear history

After merging:

  • Delete the feature branch (keeps repo clean)
  • Linked issues auto-close if PR description said "Closes #123"
  • CI/CD may auto-deploy to staging/production

Issues and Project Tracking​

Creating Good Issues​

Issues track bugs, features, and tasks.

Issue template:

**What**
Clear description of issue or feature

**Why**
Business context or impact

**Acceptance Criteria**
- [ ] Criterion 1
- [ ] Criterion 2

**Additional Context**
Screenshots, links, examples

Issue best practices:

  • Use descriptive titles: "Fix: Login button not working on mobile" not "Bug"
  • Add labels: bug, feature, documentation, p0-critical, etc.
  • Assign to appropriate person or team
  • Link related issues and PRs
  • Add to project board if part of larger initiative

Labels​

Kyndof's standard labels:

Type:

  • bug - Something isn't working
  • feature - New functionality
  • enhancement - Improvement to existing feature
  • documentation - Docs changes
  • question - Question or discussion

Priority:

  • p0-critical - Urgent, blocking work
  • p1-high - Important, should do soon
  • p2-medium - Normal priority
  • p3-low - Nice to have

Status:

  • in-progress - Currently being worked on
  • blocked - Waiting on dependency
  • needs-review - Ready for review
  • wont-fix - Closed without fix

Area:

  • frontend - UI/UX work
  • backend - Server/API work
  • infrastructure - DevOps/deployment
  • security - Security-related

Project Boards​

GitHub Projects visualize work in kanban or table views.

Common boards at Kyndof:

  • Engineering Sprint Board - Current sprint work
  • Bug Triage - Bug tracking and prioritization
  • Roadmap - Long-term planning
  • Infrastructure - DevOps tasks

Board columns:

  • Backlog - Not yet started
  • Todo - Ready to work on
  • In Progress - Currently being worked
  • Review - Awaiting review
  • Done - Completed

Using project boards:

  • Drag issues between columns as status changes
  • Filter by label, assignee, milestone
  • Link PRs to issues (auto-moves card on merge)

GitHub for Technical Writers​

If you write documentation, here's your workflow:

Documentation Repositories​

wiki - Internal wiki (Markdown files)

  • Clone locally
  • Edit .md files in your text editor
  • Preview locally or in GitHub
  • Create PR for review
  • Merge when approved

Product docs - User-facing documentation

  • Similar to wiki workflow
  • More rigorous review process
  • May have automated build/deploy

Markdown Files​

Markdown is plain text with simple formatting:

# Heading 1
## Heading 2

**bold** and *italic*

[Link text](https://url.com)

- Bullet list
- Another item

1. Numbered list
2. Another item

`inline code`

```code block```

Preview markdown:

  • In VS Code: Right-click file → Open Preview
  • On GitHub: Files show rendered when viewed
  • Tools like Typora or iA Writer show live preview

Documentation Workflow​

  1. Create branch: docs/add-slack-guide
  2. Add or edit .md files
  3. Preview locally to check formatting
  4. Commit with message: docs: add Slack integration guide
  5. Push branch
  6. Create PR
  7. Request review from subject matter expert
  8. Merge when approved

GitHub for Designers​

Designers interact with GitHub for design systems and asset versioning:

Design File Tracking​

Figma files:

  • Don't store in GitHub (too large)
  • Document link in README
  • Track versions in CHANGELOG

Design system code:

  • CSS, component files in GitHub
  • Designers review PRs for visual changes
  • Ensure implementation matches design

Image assets:

  • Icons, illustrations committed to repo
  • Use PNG/SVG (not layered PSDs)
  • Optimize before committing

Reviewing Visual Changes​

Screenshot reviews:

  1. Developer adds before/after screenshots to PR
  2. Designer reviews visual accuracy
  3. Comment on spacing, colors, fonts
  4. Approve or request changes

Local preview:

  1. Pull PR branch locally
  2. Run app in development mode
  3. Interact with changes live
  4. Provide detailed feedback

GitHub Actions and Automation​

GitHub Actions automate workflows (CI/CD).

Common Workflows at Kyndof​

On every PR:

  • Run tests automatically
  • Check code formatting (linting)
  • Build to ensure no errors
  • Post results as PR checks

On merge to main:

  • Build production assets
  • Run full test suite
  • Deploy to staging
  • Notify Slack channel

Scheduled:

  • Nightly security scans
  • Weekly dependency updates
  • Monthly analytics reports

Understanding Check Status​

PR shows status checks at bottom:

  • ✅ All checks passed - Good to merge
  • ❌ Some checks failed - Fix before merging
  • 🟡 Checks running - Wait for completion

Common failures:

  • Test failures - Code broke existing functionality
  • Lint errors - Code style issues
  • Build errors - Code doesn't compile

Click "Details" to see full logs.

Security and Access​

Repository Visibility​

  • Private - Only Kyndof org members (most repos)
  • Public - Anyone can see (open source projects)
  • Internal - Enterprise only (not applicable)

Ask before making public. Default is private.

Access Levels​

Read - Can view and clone repo

  • All Kyndof employees have read access to most repos

Write - Can push directly to branches

  • Team members on projects

Admin - Can change settings, manage access

  • Repository maintainers and engineering leads

Ask in #team-engineering if you need different access.

Secrets and Credentials​

Never commit:

  • API keys
  • Passwords
  • Private keys
  • Access tokens
  • Database credentials

How to handle secrets:

  • Use environment variables
  • Store in GitHub Secrets (for Actions)
  • Use 1Password for team credentials
  • Reference secrets by name, not value

If you accidentally commit a secret:

  1. Tell #team-engineering immediately
  2. Rotate/revoke the credential
  3. Remove from git history (ask for help)

GitHub Desktop for Beginners​

GitHub Desktop is easier than command line for beginners.

Getting Started​

  1. Download GitHub Desktop
  2. Sign in with GitHub account
  3. Clone your first repository
  4. Make changes in your editor
  5. Commit in GitHub Desktop
  6. Push to GitHub

Basic Workflow​

Make changes:

  1. Open repo in GitHub Desktop
  2. Click "Open in [your editor]"
  3. Edit files, save
  4. Return to GitHub Desktop
  5. See changes listed

Commit changes:

  1. Review changed files
  2. Write commit summary
  3. Write detailed description (optional)
  4. Click "Commit to [branch]"

Push to GitHub:

  1. Click "Push origin" button
  2. Changes sync to GitHub.com
  3. Create PR from website

Create branch:

  1. Click "Current Branch" dropdown
  2. Click "New Branch"
  3. Name it (e.g., feature/my-feature)
  4. Click "Create Branch"

Command Line Basics​

For developers and power users, command line is faster:

Essential Git Commands​

Setup:

git config --global user.name "Your Name"
git config --global user.email "you@kyndof.com"

Clone repository:

git clone https://github.com/kyndof/repo-name.git
cd repo-name

Daily workflow:

# Check status
git status

# Create branch
git checkout -b feature/my-feature

# Stage changes
git add file.txt
# Or stage all: git add .

# Commit
git commit -m "feat: add new feature"

# Push to GitHub
git push origin feature/my-feature

# Pull latest changes
git pull origin main

# Switch branches
git checkout main

Keeping branch updated:

# From your feature branch
git checkout main
git pull origin main
git checkout feature/my-feature
git merge main

Common Git Issues​

"Merge conflict"

  • Two people edited same lines
  • Git can't auto-merge
  • Open conflicted files, choose which changes to keep
  • Mark as resolved, commit

"Detached HEAD"

  • Checked out specific commit instead of branch
  • Create branch: git checkout -b new-branch-name

"Your branch is behind origin/main"

  • Remote has newer commits
  • Pull: git pull origin main

"Cannot push - updates were rejected"

  • Someone else pushed first
  • Pull first: git pull --rebase origin main
  • Resolve conflicts if any, then push

Best Practices​

Commit Best Practices​

Write good commit messages:

  • Use imperative mood: "Add feature" not "Added feature"
  • Be specific: "Fix null pointer in user auth" not "Fix bug"
  • Reference issues: "Fix login bug (closes #123)"

Commit frequently:

  • Small, focused commits
  • Each commit should be logical unit
  • Easier to review and revert if needed

Don't commit:

  • Large binary files (images > 1MB, use S3)
  • Generated files (build output, node_modules)
  • IDE-specific files (.vscode, .idea)
  • Personal config files

Branch Best Practices​

Keep branches focused:

  • One feature or fix per branch
  • Short-lived (days, not weeks)
  • Merge and delete when done

Stay up to date:

  • Regularly merge main into your branch
  • Avoid long-running divergent branches
  • Resolve conflicts early

Delete merged branches:

  • Keeps repository clean
  • Prevents confusion
  • Can always recover if needed

Pull Request Best Practices​

Before creating PR:

  • Test your changes locally
  • Ensure all tests pass
  • Update documentation if needed
  • Self-review the diff

In PR description:

  • Explain what and why
  • Link related issues
  • Add screenshots for UI changes
  • List steps to test

During review:

  • Respond to all comments
  • Push fixes as new commits (easier to review)
  • Don't force-push while under review
  • Mark conversations as resolved when addressed

After approval:

  • Squash commits if many small ones
  • Ensure CI passes
  • Merge promptly
  • Delete branch

Getting Help​

Resources​

Kyndof-specific:

  • Ask in #team-engineering Slack channel
  • Check this guide
  • Review existing PRs for examples

GitHub documentation:

Git learning:

Training​

Onboarding sessions:

  • Engineering team holds Git/GitHub training for new hires
  • Schedule with your manager

Pairing:

  • Ask teammate to walk you through first PR
  • Screen share for real-time help

Navigation:

Last Updated: 2026-02-03