[Proposal] Mobile GitHub Project Reorganization
Overview
The goal of these proposed changes is to create a Roadmap that clearly communicates the status of design and development efforts. As a result of these changes we hope the community will be able to see what is actively being designed/developed, the status of these efforts (including blockers), and how they can get involved. In addition, we propose changes that will help clarify which stories within epics are designed but placed in a development backlog. Proceeding with these changes will reduce duplicative product, design, and development work, and increase collaboration among providers on key initiatives.
This document is organized into two main sections:
A brief review of the current GitHub Project used to manage the Mobile Roadmap;
Proposed changes for consideration by the larger Open edX Mobile community.
This GitHub reorganization proposal is part of a larger initiative to improve the definition and execution of the Mobile Roadmap.
As a note: we expect continual re-evaluation on whatever process the community lands on for organizing and managing the GitHub Mobile Roadmap. This document suggests a starting point.
Proposed Changes
Below is a brief summary of the main changes proposed in this document. Details on the thinking behind these changes are explained below.
Introduce a new repository called openedx-apps-mobile to hold all Epics and stories
Move to a pattern where iOS and Android repositories hold pull requests and bug issue, but not epics/stories
Change status labels in order to have clear lanes of ownership
Review: Open edX Mobile Roadmap in GitHub Projects Current Utilization
Currently, the issues in the GitHub Project consist of bugs, epics, feature proposals, skeleton issues for future work, and more. “Issues” in GitHub are used to track bugs, epics, stories, designs, and ideas. One limitation of issues is that they must be created in a repository.
In the current GitHub Project for mobile, issues are created and labeled Epics in the iOS repository, and within those epics, iOS and Android epics are created to track each epic in a particular platform. This means that the roadmap has three issues per epic, and all three must be tracked separately.
As an example: Open edX Mobile ECommerce Capabilities · Issue #427 · openedx/openedx-app-ios Open edX Mobile ECommerce Capabilities is tied to Android issues by mention [Android] ECommerce Capabilities · Issue #293 · openedx/openedx-app-android [Android] Ecommerce Capabilities, and to iOS by mention [iOS] ECommerce Capabilities · Issue #399 · openedx/openedx-app-ios [iOS Ecommerce Capabilities.
Each quarter, one issue is created for iOS and Android respectively for miscellaneous bugs and cleanup tasks. These issues contain tasks lists with all the outstanding bugs/cleanup issues. Task lists is a feature that will be deprecated at the end of April 2025.
Very few epics have child issues. This means for larger initiatives (such as Course Content View) there are no sub-issues detailing stories or smaller segments of work to be developed. For those details, contributors must reference Confluence proposals, Figma files, and Slack/ email threads for clarity.
Development efforts on the Open edX Mobile App are currently tracked by platform (iOS or Android). In some cases, two issues are created per epic (one for iOS and one for Android) and in some three (one for iOS, one for Android, and one parent issue in the iOS repository to house both platform epics).
This leads to Roadmap views such as below, where the amount of issues with varied naming standards creates a board that is hard to understand.
Status columns in the Roadmap kanban are:
No Status (63 issues)
Extended Backlog / Icebox (27 issues)
Prioritized Backlog (18 issues)
In Discovery / Definition (22 issues)
In Development (13 issues)
In Code Review / Final Acceptance (5 issues)
Done (287 issues)
The repository for iOS can be found here: GitHub - openedx/openedx-app-ios: The mobile app for iOS for the Open EdX Platform.
The repository for Android can be found here: GitHub - openedx/openedx-app-android: The mobile app for Android for the Open EdX Platform.
Proposal: Improvements to the GitHub Project
Based on this review, we see six main areas for improvement:
Issue Hierarchy: Create a hierarchy of issues and associated repositories to make tracking projects and stories easier
Bug Tracking: Suggest a new way of organizing bugs to improve upkeep
Roadmap Views: Create different views within the GitHub project with well defined purposes with a focus on functionality
Metadata Fields: Pare down metadata fields and keep only necessary fields
Process Documentation: Create a document to explain how to use the GitHub Project optimally
1. Issue Hierarchy
Proposed Hierarchy
In order to reduce clutter and simplify the roadmap, we suggest the following hierarchy:
We also propose the following changes:
Only one epic issue per epic (ie, no iOS and Android versions of epics).
Emphasize stories which will allow for more detail within the GitHub project without the need to navigate between platforms (ie Figma/ Confluence) to understand development effort.
An emphasis on stories will allow for improved clarity on status. For example, stories with product and design definition deemed out of scope of development work can be labeled as such, allowing community members to better understand project status.
Keep stories platform agnostic. This will create a single source of truth for design feedback at the early definition stages.
Once product/design have been groomed, platform specific PRs will be created and linked to the story issue when the issues move to development.
Eliminating [iOS] and [Android] tagged epics will also improve clarity on where different types of feedback/ comments should live. Design and product feedback will be on epic or story issues. Platform specific feedback can be put in the pull requests for each story [iOS] or [Android].
Because issues in GitHub Projects must be associated with a repository, we suggest creating a new repository to hold epics and stories, openedx-app-mobile.
In addition to the above hierarchy, we propose adopting the following naming convention:
Epics should be named Epic: {Epic Name} where {Epic Name} is descriptive of the Epic (ex: Offline Mode).
Once a project is scoped and SOW signed for development, the epic should be renamed FC-XXSX Epic: {Epic Name} where “FC-XXXX” is the funded contribution code.
Out of scope stories should be moved to a sibling Epic called Epic: {Epic Name} (Future). This will allow us to track improvements/ designs that may still impact the initiative, but not within the scope of the funded contribution
PRs should have a platform tag (ie: [iOS] or [Android])
Finally, stories can also be created without a parent issue. These stories can be feature requests, general improvements, etc. Schema will manage these issues
2. Bug Tracking
Bugs should be easy for anybody to add, and the status of these bugs should be communicated with the person/organization that identified the bugs.
Bugs should be associated with Epics (funded or future) or considered general maintenance. Epics should be considered open until all sub-issues (including bugs) are marked complete. Bugs that do not fall under an epic should be assigned criticality and addressed accordingly.
Bugs should be tracked separately in its own view within GitHub Projects. More details below in the following section.
3. Roadmap Views
We propose having separate views for specific functions:
Overview: communicates a state of development to allow community members and other stakeholders to quickly see what Epics exist and in which state. The states we propose are Backlog, Next Up, In Progress, and Finished. This view will only show epics (no issues).
Unsorted Issues: this view is for product managers active on mobile projects. Schema intend to take ownership of this view.
Full Kanban: this view will show stories across various stages from design/grooming, development, acceptance testing, and complete. The columns in this view will have defined ownership by role. The purpose of this view is to communicate designs, collect feedback, and track progress.
Bug Tracking: this view will show bugs in order of priority. The purpose of this view is to better track and create accountability in managing and addressing bugs.
Overview
Epics should be organized clearly into: Epics Backlog, Next Up, In Progress, and Finished. This view should give a sense of development priorities.
This view will increase visibility of efforts in progress, and provide an easy way for providers to align related efforts.
To create this view, we will create a custom field labeled “Epic Status” with values Epics Backlog, Next Up, In Progress, and Finished.
Epics that are to be completed for a particular build release should be moved from backlog to next up.
Once design and product work has begun, epics should be moved to “In Progress.” At this stage, when an epic is moved to “in progress” product managers should review bugs, and if sensible, those bugs should be placed into epics to be squished as part of a project.
Once all stories and bugs within an epic are complete, epics should be labeled finished.
Unsorted Issues
This view is a catch-all view for all new issues and is intended to a maintenance tool. New bugs, epics, and stories will all live here. Schema will manage this view to ensure new issues have sufficient clarity for sorting. If the bug issue results from, or slots in with active development work, they will be tied to the correct epic. Otherwise, miscellaneous bugs will be organized onto the Bug Tracking view (described below).
Story issues will be tracked here to eliminate duplicate efforts, and, if created by different community members, authors will be encouraged to reach alignment.
Full Kanban
The purpose of this view is to track progress of stories. The columns of the Full Kanban view will be owned by a specific functional group as outlined below. This ownership has two benefits:
Clarifies what type of work must be done to progress the stories forward
Helps community members see how to get involved based on their background
Columns of the kanban are tied to
Backlog (owned by product): Stories that are not yet in design/development. This column should be sorted based on priority. The backlog should be reviewed quarterly as part of the general Mobile Roadmap process. [Proposal] Mobile Roadmap Feedback Process (DRAFT)
In Discovery (product): Stories that are in the requirements generation/ design phase. Issues in this column are being actively worked on. In order to move forward to the next column, stories should have preliminary requirements and designs and be ready for feedback. At this stage, stories should be added to epics.
In Grooming (product/design): Stories in this column must have proposed requirements/ designs. All necessary info (including designs/ links) should be shared here as links or directly in the content of the issue. This stage is key for community involvement and alignment. Reviewers should be tapped from the community to gather feedback through both personal outreach and working groups. When designs and requirements are reviewed by product, UX, and technical teams and alignment is reached, product leads will move the story into Development Backlog.
Ready for Development (product/ engineering): Stories in this stage have passed grooming, and the parent epics are ready for development. At this stage, epics are on hold until development is to begin. Once development has been scoped, issues deemed out of scope will be added to a newly created epic for future work (ex: Offline Download Improvements v2). This step will provide necessary clarity on which stories have been designed and may be developed by other providers/community members.
In Development (engineering): Stories in this stage are in active development or in-scope and planned for immediate development. At this stage, PR for each platform (iOS/ Android) should be linked to the story issues. Code review should occur in pull requests, and any questions from the engineering team for product should be surfaced in the story issues. Once each story has been developed, it should be passed to the final stage.
AC Testing (product/design): Stories in acceptance and QC testing. Once reviewed by the product team and passed, story issues are marked as complete. Once all issues within an epic are complete, that epic will be closed and marked as complete.
Bug Tracking
When identified, bugs should be tracked an issue. Bugs should be organized epics in development if it makes sense. Otherwise, bugs should be organized based on criticality.
4. Issue Metadata / Templates
Currently, the custom metadata fields in the Mobile Roadmap GitHub projects are:
Confluence, Development, Design Discovery, Product Definition, Theme, Development Start, Target Completion, Definition / Discovery Start, Current Focus, Priority Field (edX), Roadmap Quarter, and Funded Contribution.
In a brief scan of current issues, almost all custom fields are left empty.
In order to keep fields manageable and functional, we propose the following custom fields:
Epic Status: used to track epics in the Overview view. Options should be: Epics Backlog, Next Up, In Progress, and Finished.
Priority: This is used primarily to help sort bugs, but also for stories that are not part of a particular epic.
Platform: This is used to categorize issues. Options should be: Both, iOS, Android. Typically this will be Both, but some cases (ex: a platform specific bug) can be labeled iOS. These issues would still be in the openedx-app-mobile repository, but would help provide clarity.
We plan to remove unused custom fields at a later date.
Templates
Story issues should have a tasklist with a checkbox for “iOS implementation complete” and “Android implementation complete.” When PRs are merged, these should be checked off.
Open Questions
Open questions to consider:
Q: How will we handle tracking different pacing between platforms in the new system where there is only one issue per story?
Q: How should platform-specific bug issues be created? If there is a bug in iOS, should the bug issue be created in the general mobile repository or in the specific platform in which the bug appeared?
Q: How will we track platform-specific work, ie: work done to migrate to new versions of operating systems?