Request for changes

Guide to proposing a new or a change to an existing pattern in the codebase or development workflows.

• Why should we use this process?

• Process goals

• RFC process

• Reasons for reference implementation

Why should we use this process?

Engineering teams, especially at scale, require guidelines and patterns to be effective, transparent and enable adoption.

Process goals

This guide aims to achieve the following:

• Provide a Single Source of Truth (SSOT) to track all process changes, so that it's easy for stakeholders to understand decisions

• Create a straightforward format for the team to make, discuss and implement decisions regarding process changes

• Ensure that there is a DRI (Directly Responsible Individual) so that proposals don't go stale

RFC process

1. Create an issue using the provided templates and include a reference implementation

   • Requests not using a template can be automatically rejected

2. Share the RFC issue across shared mediums

   • Relevant engineering meeting

   • Engineering channel (slack, teams, ect)

   • Connect with relevant stakeholders (i.e. team leads)

3. Give the stakeholders time to review the proposal and provide comments about the proposal

4. If there is a strong consensus towards a decision

   • Connect with Engineering Manager to groom and include the issue in a relevant timeline

   • Implement the process change using GitFlow

   • Announce process change across appropriate mediums

5. If the decision is not to proceed, the issue should updated with the reasons for disagreement and closed

Reasons for reference implementation

When an RFC introduces a new pattern the RFC describes high-level design decisions about how developers should implement the pattern in the codebase.

In practice, implementing these patterns can uncover technical constraints and low-level design decisions that can profoundly change the high-level guidelines in the RFC.

Slightly different understandings of the proposed changes can be more easily understood when the stakeholders look concrete examples.

A reference implementation should satisfy the following conditions:

• Provide an example in a real-world situation by using the pattern suggested in the RFC to implement a reference solution for an existing feature.

• Provide metrics that demonstrate performance or productivity improvements.

As the RFC progresses, it is recommended that the reference implementation also progresses with it. Ideally, upon acceptance of an RFC, the reference implementation should be capable of being merged as the initial step towards implementing the RFC in its entirety.

There are situations where creating a reference implementation may not be appropriate because the proposal does not involve altering code practices or patterns. In such cases, it is advisable to substitute the reference implementation with an alternative exploration of the specifics, such as a cost-benefit analysis, sample documentation, ect.