|Authors||Jeremy Bowman <firstname.lastname@example.org>|
|Arbiter||Adam Stankiewicz <email@example.com>|
|Review Period||2018-06-14 - 2018-08-15|
|Resolution||Original pull request|
Proposes a process for achieving large and/or long-term Open edX project goals via the definition and distributed completion of many small, straightforward development tasks.
There are often relatively straightforward changes to the Open edX codebase which prove difficult to accomplish due to the sheer amount of code involved. These are not major new features or complex refactorings of the code, but rather things like:
Such projects can involve changing hundreds of files and thousands of lines of code...but they are fundamentally composed of dozens of routine, localized changes which can be made independently and without any particular prior knowledge of how the Open edX code is structured. It is very difficult for any one organization to prioritize tackling one of these projects by itself, but once broken down into very small pieces, the benefits of distributing them across the entire community become rapidly apparent.
The Incremental Improvements (INCR) JIRA project is home to small, straightforward tasks which must be finished in order to achieve larger, long-term objectives of the Open edX community. All tickets in it should have the following characteristics:
Note that it is entirely possible that an epic in the INCR project may not be achievable purely through the completion of INCR tickets. There may be changes required which require more domain knowledge of the existing code, can’t realistically be broken down into small enough tasks, or just aren’t understood well enough to allow writing a sufficiently detailed ticket description without basically completing the task. This is all fine; INCR tickets should only be written for the parts of the project for which they are appropriate. The rest of the work can be coordinated in a variety of ways; examples of such coordination are given later below.
It is also not necessary to immediately detail all of the INCR tickets that
will ultimately belong to an INCR epic when it is first created. It is
usually sufficient to initially create just a handful of tickets that allow
several developers with any appropriate skill sets to contribute. More should
be written as the tasks are completed, so there is always something available
to work on for those interested in contributing. Tasks which depend on other
work being finished first but otherwise qualify as INCR tickets may be created
as such, but should immediately have their status marked as
Blocked and be
linked to the tickets which are blocking progress.
Incremental Improvement tickets are appropriate for many kinds of contributors, including (but not limited to):
When enough of an epic is complete that the scope of remaining work becomes more manageable (or when an external deadline like end of support for a current dependency approaches), one or more organizations in the community may decide that it’s worth making that epic a higher priority, assigning even more developers to work on INCR tickets.
Once the contributor is ready to submit their changes, the process will typically go roughly as follows:
New top-level INCR epics should be proposed in an Open edX discussion forum (such as the #architecture channel on Slack), and only created if there is consensus that they should be added at that time. The total number of active epics should be kept limited to avoid dilution of effort between too many projects. An epic’s author can delegate the creation of individual tickets within it as appropriate.
Historically, edX has been relatively poor at pre-emptively completing major framework upgrades (like Django 1.11 or Python 3). We have also been somewhat inefficient in replacing working but problematic code with newer solutions which have already been demonstrated to work better in other parts of the code. A major contributing factor in this is that we have not effectively enabled the Open edX community to share the burden of doing this maintenance work. edX keeps prioritizing work on new features in high demand by partners in the community, while those partners get frustrated that it isn’t clear how to help and the code is somewhat dated and difficult to work with. People new to the project are often eager to contribute, but have no idea where to start and get little useful guidance in that regard.
The goal of the Incremental Improvements process is to identify, document, and bring attention to small chunks of work that can be performed by a broad spectrum of community members and make meaningful progress towards larger shared objectives. The hope is that this will enable all of the following:
(Note that in the context of this draft, “rejected” does not mean that the alternative has been completely ruled out, rather that it seemed implausible when first considered.)
There are limitations to using an edX-managed JIRA project as the primary system of coordination for Incremental Improvement tickets. Contributors outside of edX have limited ability to update and comment on the tickets, and the system is not exactly intuitive for users who have not used JIRA before. Nevertheless, the other considered options seem to have even greater obstacles:
Other suggestions for handling this more elegantly are welcome, but understand that there is significant resistance against either adding a second issue tracker that edX employees would need to routinely use and monitor, or moving core edX development from JIRA to a different issue tracker.