Development Git Workflow

Git Workflow & Collaboration

A streamlined guide for contributing to EduLite.

Quick Start

# 1. Fork & clone
git clone https://github.com/YOUR_USERNAME/EduLite.git
cd EduLite
git remote add upstream https://github.com/ibrahim-sisar/EduLite.git

# 2. Create feature branch
git checkout main
git pull upstream main
git checkout -b feat/123-your-feature

# 3. Make changes & commit
git add .
git commit -m "feat: add your feature"

# 4. Push & create PR
git push origin feat/123-your-feature
# Then open PR on GitHub

Finding Work

Where to Look

• GitHub Issues: Browse [open issues](https://github.com/ibrahim-sisar/EduLite/issues), especially those labeled good first issue
• Discord: Check #help-wanted for urgent needs
• Discussions: For broader feature proposals

Issue Templates

When you click "New Issue" you'll see several templates:

• Newbie Backend / Newbie Frontend — Guided templates with a task description, definition of done, skills you'll practice, files to look at, and testing tips. Start here if you're newer to the project.
• Senior Backend / Senior Frontend — Structured templates with problem statement, requirements, architecture context, and testing requirements. For experienced contributors who need context, not hand-holding.
• Generic Issue — For anything that doesn't fit the above (bugs, docs, infrastructure, ideas).

All templates include a Claiming This Task section — check it before starting work.

Claiming Issues

1. Check if unassigned
2. Comment your intention: "I'd like to work on this"
3. Wait for assignment or self-assign
4. Start work only after claiming

Note: Issues may be unassigned after 7 days of inactivity.

Branch Naming

Format: type/issue-number-description

• feat/ - New features
• fix/ - Bug fixes
• docs/ - Documentation
• refactor/ - Code restructuring
• test/ - Adding tests
• chore/ - Maintenance

Examples:

feat/123-add-study-timer
fix/456-login-error
docs/789-update-api-guide

Commit Standards

Format

type(scope): brief description

Types

• feat: New feature
• fix: Bug fix
• docs: Documentation
• style: Formatting (no code change)
• refactor: Code restructuring
• test: Adding tests
• chore: Maintenance

Examples

git commit -m "feat: add study timer component"
git commit -m "fix: resolve login error on slow connections"
git commit -m "docs: update installation guide"

Best Practices

• One commit per logical change
• Write clear, descriptive messages
• Keep commits atomic and reversible

Pull Requests

PR Title

Type: Brief description

Examples:

• feat: add study timer to dashboard
• fix: resolve WebSocket reconnection issue

PR Template

Every PR auto-populates with our template. You must complete it — PRs that skip the template or leave checklist items unchecked will be sent back.

The template includes:

Description — What the PR does, with a Closes #<issue-number> link. Every PR must link to an issue.

Mandatory Checklist — All 8 items must be checked before merge:

• Read and followed CONTRIBUTING.md
• Linked the related issue
• Branch is up to date with main
• Tested changes locally
• Added or updated tests
• No new linting errors
• Clear, descriptive commit messages
• Updated documentation if applicable

What Changed — Brief summary of changes and why files were touched.

How to Test — Specific steps a reviewer can follow to verify your work.

Screenshots — For frontend or UI changes, include before/after screenshots.

PR Guidelines

• Keep PRs focused - One feature/fix per PR
• Link issues - Use "Closes #123" to auto-close
• Add screenshots - For UI changes
• Test thoroughly - Including edge cases
• Be responsive - Address feedback promptly

Code Quality

Backend Development

For Python/Django code, we use automated tools to ensure consistency:

• Pre-commit hooks: Automatically format code and run checks before commits
• Black: Python code formatter (line-length: 88)
• mypy: Optional type checking

To set up (recommended for backend contributors):

pip install pre-commit
pre-commit install

For detailed pre-commit configuration, see our Backend Pre-commit Guide.

General Standards

• Follow existing code patterns
• Add tests for new features
• Update documentation as needed
• Consider performance on slow networks

Code Reviews

For Authors

• Self-review first
• Ensure CI passes
• Respond to all feedback
• Mark conversations as resolved

For Reviewers

• Be constructive and specific
• Focus on code, not person
• Explain the "why"
• Acknowledge good work

Review Example

# Suggesting improvement
"Consider using `select_related` here to reduce database queries:

users = User.objects.select_related('profile').all()

This changes from N+1 to 1 query."

Handling Conflicts

# Update your branch
git fetch upstream
git merge upstream/main

# If conflicts exist
git status  # See conflicted files
# Edit files to resolve
git add resolved-file.js
git commit -m "fix: resolve merge conflicts"
git push origin your-branch

Useful Commands

# Daily workflow
git status                    # Check current state
git add .                     # Stage changes
git commit -m "message"       # Commit changes
git push origin branch        # Push to fork
git pull upstream main        # Update from main

# Branch management
git branch                    # List branches
git branch -D branch-name     # Delete local branch
git checkout -b new-branch    # Create and switch to new branch

# Fixing mistakes
git commit --amend           # Modify last commit
git reset HEAD~1             # Undo last commit (keep changes)
git stash                    # Temporarily store changes
git stash pop                # Restore stashed changes

Getting Help

• Discord: Ask in #help channel
• GitHub Discussions: For broader questions
• Documentation: Check project wikis and guides

Remember: Everyone starts somewhere. Don't hesitate to ask questions!

---

For more detailed information on specific topics, see our dedicated guides in the wiki.