Skip to content

PROJECT_GUIDE.md

Latest commit

 

History

History
486 lines (365 loc) · 16.4 KB

PROJECT_GUIDE.md

File metadata and controls

486 lines (365 loc) · 16.4 KB

🏷️ GitHub Project Management Guide

Comprehensive instructions for managing the OpenCare project using GitHub features like Projects, Issues, Labels, and Milestones.

📋 Table of Contents

📋 Project Board Setup

Our project uses GitHub Projects for task management and workflow tracking. The project board is organized into the following columns:

Column Purpose Description
Backlog Task Planning New issues and feature requests
To Do Ready for Development Approved and prioritized tasks
In Progress Active Development Tasks currently being worked on
Review Code Review Completed tasks awaiting review
Testing Quality Assurance Tasks in testing phase
Done Completed Successfully completed and deployed tasks

🎯 Board Configuration Tips

  • Automation: Set up automatic column transitions based on PR status
  • Field Configuration: Add custom fields for story points, assignees, and due dates
  • Views: Create different views (Table, Board, Timeline) for different team needs
  • Filters: Use filters to focus on specific components or priorities

🏷️ Issue Labels & Categories

We use a comprehensive labeling system to categorize and prioritize issues effectively.

🔴 Priority Labels

Label Color Description Usage
priority: critical 🔴 Red Must be fixed immediately Security issues, critical bugs
priority: high 🟠 Orange Important for next release Major features, significant bugs
priority: medium 🟡 Yellow Normal priority Regular features, minor bugs
priority: low 🟢 Green Nice to have Enhancements, documentation

🎨 Type Labels

Label Color Description Usage
type: bug 🐛 Purple Something isn't working Error reports, unexpected behavior
type: feature ✨ Blue New functionality New features, enhancements
type: documentation 📚 Green Documentation updates README, API docs, guides
type: enhancement 🔧 Orange Improvement to existing feature UI/UX improvements, performance
type: question ❓ Gray General questions Support, clarification needed
type: duplicate 🔄 Gray Issue already exists Duplicate reports
type: invalid ❌ Red Issue not applicable Wrong repository, invalid bug

🧩 Component Labels

Label Color Description Usage
component: frontend 🎨 Blue Frontend (Next.js) related UI components, pages, styling
component: backend ⚙️ Green Backend (Spring Boot) related APIs, services, database
component: mobile 📱 Purple Mobile app related React Native features
component: database 🗄️ Brown Database related Schema, migrations, queries
component: infrastructure 🏗️ Gray DevOps, deployment Docker, CI/CD, hosting
component: security 🔒 Red Security related Authentication, authorization

📊 Status Labels

Label Color Description Usage
status: blocked 🚫 Red Cannot proceed Waiting for dependency
status: in-review 👀 Blue Under code review PR submitted, awaiting review
status: needs-info ℹ️ Yellow Requires more information Missing details, clarification
status: wont-fix ❌ Gray Will not be implemented Out of scope, deprecated

🎯 Difficulty Labels

Label Color Description Estimation
difficulty: beginner 🟢 Green Good for new contributors 1-2 hours
difficulty: easy 🟡 Yellow Simple changes 2-4 hours
difficulty: medium 🟠 Orange Moderate complexity 4-8 hours
difficulty: hard 🔴 Red Complex implementation 8-16 hours
difficulty: expert ⚫ Black Very complex 16+ hours

🏷️ Special Labels

Label Color Description Usage
good first issue 🟢 Green Perfect for newcomers Simple, well-documented tasks
help wanted 🟡 Yellow Needs community help Open for contribution
sprint: current 🔵 Blue Current sprint focus High priority for this sprint
sprint: next 🟣 Purple Next sprint planning Planning phase

📊 Issue Templates

We use standardized issue templates to ensure consistency and completeness.

🐛 Bug Report Template

## 🐛 Bug Description
Brief description of the bug

## 🔍 Steps to Reproduce
1. Go to '...'
2. Click on '...'
3. Scroll down to '...'
4. See error

## ✅ Expected Behavior
What you expected to happen

## ❌ Actual Behavior
What actually happened

## 📱 Environment
- OS: [e.g., Windows 10, macOS, Ubuntu]
- Browser: [e.g., Chrome, Firefox, Safari]
- Version: [e.g., 22]
- Device: [e.g., Desktop, Mobile, Tablet]

## 📸 Screenshots
If applicable, add screenshots to help explain the problem

## 📝 Additional Context
Add any other context about the problem here

## 🔗 Related Issues
Link to any related issues or pull requests

## 📋 Labels
- [ ] `type: bug`
- [ ] `component: [frontend/backend/mobile/database]`
- [ ] `priority: [critical/high/medium/low]`
- [ ] `difficulty: [beginner/easy/medium/hard/expert]`

🚀 Feature Request Template

## 🚀 Feature Description
Brief description of the feature you'd like to see

## 🎯 Problem Statement
What problem does this feature solve?

## 💡 Proposed Solution
Describe the solution you'd like to see

## 🔄 Alternative Solutions
Describe any alternative solutions you've considered

## 📱 Platform
- [ ] Web Application
- [ ] Mobile App (iOS)
- [ ] Mobile App (Android)
- [ ] All Platforms

## 🎨 UI/UX Considerations
Any specific design requirements or user experience considerations

## 🔗 Related Features
Link to any related features or existing functionality

## 📝 Additional Context
Add any other context or screenshots about the feature request

## 📋 Labels
- [ ] `type: feature`
- [ ] `component: [frontend/backend/mobile/database]`
- [ ] `priority: [critical/high/medium/low]`
- [ ] `difficulty: [beginner/easy/medium/hard/expert]`

📚 Documentation Update Template

## 📚 Documentation Update
Brief description of what documentation needs to be updated

## 🎯 What Needs Updating
- [ ] README files
- [ ] API documentation
- [ ] User guides
- [ ] Developer documentation
- [ ] Code comments

## 📝 Specific Changes
Describe the specific changes needed

## 🔗 Related Code Changes
Link to any related code changes or issues

## 📋 Labels
- [ ] `type: documentation`
- [ ] `component: [frontend/backend/mobile/database]`
- [ ] `priority: [critical/high/medium/low]`

⏱️ Time Estimation Guidelines

We use story points and time estimates to plan and track development progress.

📊 Story Point Scale (Fibonacci)

Points Description Time Estimate Examples
1 Very simple 1-2 hours Typo fixes, simple text changes
2 Simple 2-4 hours Minor UI adjustments, simple validations
3 Small 4-8 hours New form fields, basic CRUD operations
5 Medium 1-2 days Complex forms, API endpoints, database queries
8 Large 3-5 days New features, complex integrations
13 Very Large 1-2 weeks Major features, architectural changes
21 Epic 2+ weeks Break into smaller stories

📋 Estimation Rules

  1. Break Down Large Tasks: If a task is estimated at 8+ points, consider breaking it down
  2. Consider Dependencies: Account for time needed to understand existing code
  3. Include Testing: Estimation should include unit tests and basic testing
  4. Buffer for Unknowns: Add 20% buffer for unexpected challenges
  5. Review Time: Include time for code review and feedback incorporation
  6. Documentation: Factor in time for updating relevant documentation
  7. Integration Testing: Consider time needed for integration testing

🔄 Estimation Process

  1. Initial Estimate: Developer provides initial story point estimate
  2. Team Discussion: Team discusses complexity and dependencies
  3. Final Estimate: Team agrees on final story point value
  4. Time Conversion: Convert story points to actual time estimates
  5. Regular Review: Revisit estimates if scope changes significantly

📈 Estimation Tips

  • Compare Similar Tasks: Look at completed similar tasks for reference
  • Consider Team Experience: Factor in team member expertise level
  • Account for Learning: New technologies or approaches need extra time
  • Review Historical Data: Use past sprint velocity for better estimates
  • Break Down Complex Tasks: Divide large tasks into smaller, estimable pieces

🔄 Workflow Process

📋 Issue Lifecycle

New Issue → Triage → Estimation → Assignment → Development → Review → Testing → Done

🔍 Detailed Workflow

1. Issue Creation

  • Use appropriate template
  • Add relevant labels
  • Set priority and component
  • Provide clear description
  • Add screenshots or examples if applicable

2. Triage & Planning

  • Review and categorize issues
  • Estimate story points
  • Assign to appropriate milestone
  • Set assignee if known
  • Add any missing labels or information

3. Development

  • Move issue to "In Progress"
  • Create feature branch following naming convention
  • Update issue with progress updates
  • Link commits to issue using #issue-number
  • Add any blockers or dependencies

4. Review & Testing

  • Submit pull request
  • Move issue to "Review"
  • Address feedback and comments
  • Move to "Testing" after approval
  • Update issue with testing progress

5. Completion

  • Verify functionality meets requirements
  • Update documentation if needed
  • Move to "Done"
  • Close issue
  • Celebrate completion! 🎉

🚦 Workflow Rules

  • One Issue Per Branch: Each feature branch should address one issue
  • Regular Updates: Update issue status at least daily
  • Clear Communication: Comment on issues when status changes
  • Link Everything: Connect commits, PRs, and related issues
  • Test Before Moving: Ensure functionality works before moving to next column

📅 Milestone Management

We use milestones to organize releases and track progress.

🏗️ Milestone Structure

  • Version Number: e.g., "v1.2.0"
  • Due Date: Target release date
  • Description: Key features and goals
  • Issues: Linked issues and pull requests

📋 Release Planning

  1. Feature Freeze: 2 weeks before release
  2. Code Freeze: 1 week before release
  3. Testing Phase: Final week before release
  4. Release Day: Deploy and tag release

🎯 Milestone Best Practices

  • Realistic Scope: Don't overcommit to a single milestone
  • Clear Goals: Define what "done" means for each milestone
  • Regular Check-ins: Review progress weekly
  • Flexibility: Adjust scope if needed to meet deadlines
  • Celebration: Acknowledge team achievements

🏷️ Tagging Best Practices

📝 Commit Message Tags

Use prefixes in commit messages to categorize changes:

feat: add new doctor search functionality
fix: resolve authentication token issue
docs: update API documentation
style: improve button styling
refactor: restructure user service
test: add unit tests for doctor service
chore: update dependencies
perf: optimize database queries
ci: update GitHub Actions workflow
build: update build configuration

🌿 Branch Naming Convention

feature/doctor-search
bugfix/auth-token-issue
hotfix/security-patch
release/v1.2.0
docs/api-update
test/unit-tests
refactor/user-service

🏷️ Issue Labeling Strategy

  • Start with Type: Always add a type label first
  • Add Component: Specify which part of the system is affected
  • Set Priority: Determine urgency level
  • Indicate Difficulty: Help with task assignment
  • Use Status: Track current state
  • Special Labels: Add any relevant special labels

📊 Progress Tracking

📈 Velocity Metrics

  • Track story points completed per sprint
  • Monitor estimation accuracy
  • Identify bottlenecks and blockers
  • Plan capacity for future sprints
  • Analyze team performance trends

📉 Burndown Charts

  • Visual representation of sprint progress
  • Track remaining work vs. time
  • Identify if sprint goals are achievable
  • Adjust scope if necessary
  • Celebrate progress milestones

📊 Key Performance Indicators

  • Sprint Velocity: Average story points completed per sprint
  • Estimation Accuracy: How close estimates are to actual time
  • Issue Resolution Time: Time from creation to completion
  • Code Review Time: Time spent in review phase
  • Testing Coverage: Percentage of issues properly tested

🚀 Quick Start for Contributors

1. Set Up Project Board

  • Go to GitHub Projects
  • Familiarize yourself with the board structure
  • Review current issues and priorities
  • Understand the workflow columns

2. Choose an Issue

  • Look for issues labeled good first issue or help wanted
  • Check difficulty level matches your experience
  • Ensure the issue is not already assigned
  • Read the full description and requirements

3. Start Working

  • Comment on the issue to claim it
  • Move it to "In Progress"
  • Create a feature branch following naming convention
  • Update the issue with progress updates
  • Link commits to the issue

4. Submit Work

  • Create a pull request
  • Link it to the issue using Closes #issue-number
  • Move issue to "Review"
  • Address feedback promptly
  • Update issue status as you progress

5. Complete the Task

  • Ensure all requirements are met
  • Update documentation if needed
  • Move issue to "Done"
  • Close the issue
  • Celebrate your contribution! 🎉

📚 Additional Resources

🔗 GitHub Documentation

📖 Agile & Project Management

🛠️ Tools & Templates

🤝 Need Help?

If you have questions about this guide or need clarification on any process:

  1. Check Existing Issues: Search for similar questions
  2. Ask in Discussions: Use GitHub Discussions for general questions
  3. Contact Maintainers: Reach out to project maintainers
  4. Contribute to Guide: Suggest improvements to this documentation

Happy Contributing! 🚀

This guide is a living document. Feel free to suggest improvements!