Code Stewardship/Resources

Best Practices

Code Stewardship seeks to improve the long-term sustainability and support of code that is deployed to the foundation's production environment. This include the health of both the code and community that supports the code. Currently the Code Stewardship encompasses four core areas: Code Health, Code Review effectiveness, task/bug effectiveness, and general planning.

Pre First Deployment

Prior to the initial deployment of a module, extension, or service to the WMF production environment, it is important that a Code Steward be identified, which is generally the team delivering the new code. The Code Steward will then be responsible to ensure that the code in question meets or exceeds Code Health standards. In addition, the Code Steward is responsible for identifying the ongoing maintenance plans for this new code.

TODO: add maintenance plan template

Involve Software Engineers in defining maintenance needs.

It is recommended that projects be started with this in mind. Understanding the maintenance burden as well as the Code Health goals will help advise decisions throughout the product development cycle. Many of the maintenance challenges encountered in legacy code are due to things like code complexity, in adequate unit test coverage, and other technological decisions that focused on the near term requirements at the cost of longer term maintenance.

Code Health

Maintaining a high degree of Code Health is key to enabling maintenance and developing a healthy and happy development community. Healthy Code is more stable, maintainable, and generally of higher quality. As Code Stewards it's important to follow sound development practices that focus on ensuring Code Health from the beginning. When at all possible, avoid development practices and anti-patterns that yield low Code Health.

Use the Code Health dashboard {TODO: add dashboard link} to help assess Code Health throughout the development lifecycle. }

Code Review

The Code Review process is an important part of ensuring a high degree of code quality. However, it can require considerable effort to do so, especially on code with a high degree of activity. For that reason, it is important to consider the ongoing impact on resourcing that the code review activity can have. From a community engagement perspective, it's also important that code reviews be done in a timely manor. All too often commits are left to languish due to various reasons causing frustration in the volunteer community and increasing the barrier of entry for new contributors.

Task Management

Generally speaking, tasks are categorized into bugs and feature requests. In the end, they are both elements of work that are being requested. It is the Code Stewards responsibility to manage the task backlog as efficiently as possible after initial triage as occurred by the Bug Wrangler. Clearly identifying those tasks that are being worked on will help minimize the confusion and frustration of those submitting the tasks. To that end it is recommend that Code Stewards follow this process:

New Task Triage

• Task is triaged by Bug Wrangler (or equivalent) and assigned appropriate project tag for the repo effected.
  • This does NOT assign ownership of task to any particular team, but rather identifies repo/code that is affected.
• Code Steward reviews new arrivals to the repo project tags that they are responsible for and further triages the task. If Code Steward is claiming ownership of the task, they assign the team's project tag to the task.
  • This notifies the broader community that the task in question will be reviewed further by the Code Stewards and has entered into the team's task management process (each team's task management process may be different).
  • This does NOT imply priority.

Example:

A new task is filed to report a potential problem with the AbuseFilter extension. Upon reporting, the Bug Wrangler identifies the potential problem as something related to the AbuseFilter extension and as a result assigns the #AbuseFilter tag to the task. During a their regular task review, the Code Steward for Abuse Filter, who happens to be the Core Platform Team, sees the new task and reviews it further. Upon internal review it is decided that the Core Platform Team will take ownership of the task and thus assigns the #CorePlatformTeam tag to the task. The Core Platform team now manages the task using their chosen internal process.

The result of the above is that the community at large is able to see what code is impacted by this task and whether or not the task is going to be addressed by the Foundation.

Existing Task Reclassification

In some instances it may be necessary to orphan a previously owned task. This can happen for a variety or reasons, but the intent is to communicate that a task's resolution will not be pursued by the Foundation. This approach is being proposed in lieu of closing tasks as the broader community may still want to track and perhaps one day resolve the task.

Annual/Mid-term/Long-term Planning

Code Stewards play a crucial role in the planning process within WMF. Historically, planning has focused a great deal on new capabilities. Although Code Stewards play an important role in new capability planning, Code Stewards should also place significant emphasis on planing for sustainability and on going support. Understanding the long-term