Skip to main content

Development Workflow

Feature-centric development structure for TopLocs ecosystem

This document outlines the development workflow approach derived from early TopLocs project organization, adapted for the current decentralized ecosystem.

GitHub Organization Structure​

Issue Labels​

  • Feature - New functionality or capabilities
  • Use Case - User interaction scenarios
  • User Story - User-focused requirements
  • Epic - Grouping related features (optional)
  • Priority: High, Medium, Low
  • Status: To Do, In Progress, Review, Done
  • Type: Frontend, Backend, API, Database, P2P, Plugin

Development Hierarchy​

  1. Epics (Optional) - Major feature groupings
  2. Features - Independent functionality units
  3. Use Cases - Specific user interaction scenarios
  4. User Stories - Granular user requirements

Feature-Centric Development Example​

Epic: Profile Management​

Issue: [Epic] Profile Management Labels: Epic, Priority: High Description: Overview of multiple profile functionality

Feature: Multiple Profile Creation​

Issue: [Feature] Multiple Profile Creation and Management Labels: Feature, Priority: High Description: Users can create and manage multiple profiles for different contexts

Use Case: Creating a New Profile​

Issue: [Use Case] User Creates a New Profile Labels: Use Case, Priority: High Process:

  1. User navigates to profile management
  2. User selects "Create New Profile"
  3. User enters profile name ("Sports", "Work", etc.)
  4. User selects interests for profile
  5. User saves new profile
  6. System confirms and displays in profile list
User Story: Create Profile​

Issue: As a user, I want to create multiple profiles Labels: User Story, Priority: High, Type: Frontend Description: "As a user, I want to create multiple profiles so I can compartmentalize different aspects of my life"

Workflow Process​

1. Feature Planning​

  • Start with user needs and scenarios
  • Create epics for major feature groups
  • Break down into specific features
  • Define use cases for each feature
  • Write user stories for implementation

2. Issue Creation​

  • Create issues following the hierarchy
  • Link child issues to parent issues
  • Use consistent labeling
  • Assign to appropriate milestones

3. Development Process​

  • Work on user stories within use cases
  • Maintain traceability to parent features
  • Update status labels as work progresses
  • Review and test at each level

4. Quality Assurance​

  • Verify user stories meet acceptance criteria
  • Test use cases end-to-end
  • Validate features against requirements
  • Ensure epics deliver complete value

Milestones and Releases​

Sprint Planning​

  • Create milestones for 2-4 week sprints
  • Group related features and use cases
  • Balance feature work with technical debt
  • Include plugin development and integration

Release Planning​

  • Major releases aligned with epic completion
  • Minor releases for feature completion
  • Patch releases for bug fixes
  • Plugin releases independent of core platform

Project Management​

GitHub Projects​

  • Use Projects for Kanban visualization
  • Organize by feature or sprint
  • Track progress across repositories
  • Monitor dependencies and blockers

Cross-Repository Coordination​

  • Tag issues that span multiple repositories
  • Use workspace-level epics for ecosystem features
  • Coordinate plugin development with core changes
  • Maintain compatibility across updates

Documentation Integration​

Issue Documentation​

  • Link issues to relevant documentation
  • Update docs when features are implemented
  • Create documentation issues for major features
  • Maintain changelog for releases

Code Documentation​

  • Document new features thoroughly
  • Update API documentation for changes
  • Include examples and usage patterns
  • Maintain plugin development guides

Community Development​

Contribution Guidelines​

  • Clear feature request process
  • Community input on use cases
  • Plugin development support
  • Code review and feedback

Communication​

  • Use GitHub Discussions for feature planning
  • Discord for real-time coordination
  • Regular community updates
  • Transparent decision-making

Best Practices​

Issue Quality​

  • Clear, actionable descriptions
  • Acceptance criteria for user stories
  • Links to related issues and documentation
  • Regular updates and progress tracking

Development Standards​

  • Follow established coding patterns
  • Write tests for new features
  • Document breaking changes
  • Maintain backward compatibility

Community Standards​

  • Respectful communication
  • Constructive feedback
  • Collaborative problem-solving
  • Inclusive development practices

Tools and Automation​

GitHub Features​

  • Issue templates for consistency
  • Automated labeling
  • Project automation
  • Integration with development workflow

Development Tools​

  • Continuous Integration
  • Automated testing
  • Documentation generation
  • Plugin development SDK

This feature-centric approach ensures that development remains focused on user value while maintaining technical excellence and community collaboration across the TopLocs ecosystem.