...
Important, but not urgent. The task should be clearly useful to perform, but not needed so badly that it can’t wait at least a few weeks for someone to notice the request and take it on.
Not controversial. If the instructions in the description are followed, it should be feasible to promptly review and merge the changes without extended deliberation.
Immediately actionable. Each maintenance issue should be doable immediately, without waiting for another change to be made first.
Captured as GitHub Issues. GitHub Issues are the current issue tracker of choice for public work on Open edX code. The issue should be created in the repository containing the code to be changed, if possible. Issues related to edx-platform should instead be created in https://github.com/openedx/public-engineering . To create an issue related to another a repository in the openedx organization for which GitHub Issues have not yet been enabled, please ask for them to be enabled via https://github.com/openedx/tcril-engineering/issues/new/choose (choose “GitHub Request - Access/Config”).
Documented clearly. The issue description doesn’t have to be a long essay, but should have enough context for an intermediate developer who hasn’t heard about the problem in an another communications channel (and perhaps doesn’t have any experience contributing to this particular repository) to effectively get started on the task.
Explicit about how to request review. The implementer may well lack access to your company’s internal communication channels, and direct pings on a PR to the issue author often get lost in a sea of GitHub notifications. Be sure to specify how the author can request review in a way that will attract reasonably timely attention.
Labeled with “help wanted” and “maintenance”. These GitHub issue labels identify the tasks as being available for work to anyone in the community with interest and motivation to help out (the “help wanted” label), and as things that eventually need to be done even if nobody steps up to volunteer for a whilecode maintenance tasks that can’t be ignored indefinitely (the “maintenace” label). If you don’t have permission to assign labels to the issue directly, you can try adding 2 separate comments to the issue containing the text “label: help wanted” and “label: maintenance”
...
Recruiting Help with Maintenance Tasks
While we definitely want help There are several candidate pools of assistants with maintenance tasks, there are a few guidelines to keep in mind when choosing one in order to minimize the amount of frustration for all parties involved:
...
and incentives for them to help. Note that some experience is required; the teams creating these tasks and reviewing code contributed for them aren’t set up to mentor people with almost no relevant experience. Junior developers are welcome, as long as they have successfully made similar contributions in the past (not necessarily in Open edX). But people still learning how to create their first pull request will probably just get frustrated until they master that skill in a more beginner-oriented context.
Core Contributors are expected to contribute 20 hours of effort per week to Open edX, and working on maintenance tasks is a perfectly acceptable use of that time.
We can (and should) create forum badges for people who complete different numbers of maintenance tasks, which may motivate others in the community to help.
Development sprints at conferences are a good venue for recruiting interested developers from outside the current Open edX community; there are often relatively experienced developers looking for a new project to get involved in, and Open edX is a relatively popular choice when someone is present to promote it.
Events such as Hacktoberfest can also attract new contributors, especially if there’s a curated set of tasks (like the maintenance tasks described here) to work on. But someone has to take the time to get things set up for participation in the event.
Boot camps and advanced programming classes sometimes seek real-world projects for students to contribute to. This can work as long as the course instructors and staff can provide the beginner support that the Open edX teams typically aren’t fully prepared to offer.
Performing Maintenance Tasks
While we definitely want help with maintenance tasks, there are a few guidelines to keep in mind when choosing one in order to minimize the amount of frustration for all parties involved:
Find a task. Here is a search query for all unassigned open maintenance tasks.
Request assignment. When you’re ready to immediately start work on the issue, assign the issue to yourself if you already have sufficient permission to do so, but in most cases you’ll need to comment on the issue to request that it be assigned to you. This may not be explicitly reflected in the “Assignee” field of the issue depending on the repo’s permissions, but at a minimum the request indicates to other interested individuals that the task is already being worked on.
Describe the changes. The PR description doesn’t need to be an essay, but it should give context about why these particular changes are being made this way. And definitely make sure to include a link to the maintenance issue that the PR was made in response to.
Request unassignment when appropriate. If something comes up and you’re unable to make progress on the task for a week or more, please state that on the original issue so it doesn’t become indefinitely blocked on you. If you have an in-progress PR and followed the advice above, there should already be a link to it in the issue history from when you mentioned it in your PR’s description.
Get checks to pass before requesting review. With rare exceptions, a failing check on a pull request is a good indication that something needs to be fixed before it can be merged. Please resolve such failures if at all possible before requesting review, so the reviewer doesn’t have to spend time pointing out the failures and deciding if it’s even worth looking at the changes any further yet.
Request review when done. Once you’ve finished the task and checks are passing, ask for review via the mechanism requested in the maintenance issue. If the issue author neglected to specify one, try @-mentioning their username in a comment on the PR to get their attention.
...