Problem Statement & Solution

A step-by-step guide on how to come up with a proposal for major technical/architectural changes to present to the team. This problem statement will help you with three things:

• generate shared understanding about the technical problem with other developers
• give you a basis for discussing the technical solution with other developers
• expose your ideas as early as possible so you can benefit from the collective knowledge of other developers

A good rule of thumb for when some change is major or not is to estimate how much time would be wasted if the pull request was rejected. If it's a couple of hours then you can probably dive head first and eat the loss in the worst case. Otherwise, producing a problem statement and discussing it with the other developers will save everyone lots of time.

Producing a problem statement is as easy as:

1. Copy this document to another wiki page, Etherpad, presentation or another medium
2. Answer the questions it poses as accurately as you can
3. Present the document to other developers of the team
4. Incorporate the feedback they give you. Present it again. Repeat until happy.
5. Implement

Please stick to this format so it's easier for all of us to get used to this.

NOTE: you can search by "Problem Statement & Solution Document" inside this repository to find existing wiki pages following the PS&S format.

Reality?

In this section, you should describe the state of the workflow and user interaction as of today. The more accurate you describe the reality, the more exact you will understand the consequences in the next section.

How is the workflow right now?

• Which kind of users are involved?
• Which models/services are involved?
• Which OBS subsystems (delayed jobs, sphinx, caches etc.) are involved?

Consequences?

In this section, you should describe the downsides of the reality as of today. The more exact you understand the consequences, the more precise you will be able to illustrate the future in the next section.

Why do we need to change the workflow that we have right now?

• What is wrong with the workflow?
• What are the problems with how the models/services are used?
• What are the pain points with involved OBS subsystems?

Future?

In this section, you should describe the desired state of the workflow and user interaction in the future. The more precise you illustrate the future, the more solid your implementation proposal in the next section will be.

How should the workflow be in the future?

• Which kind of users are involved?
• Which models/services are involved?
• Which OBS subsystems (delayed jobs, sphinx, caches etc.) are involved?

Proposal!

Describe one (the best 🚀) potential way to make the future you previously described happen.

What do we have to change to be able to implement this new workflow?

• How do we have to change models/services?
• What are the needed changes to other OBS subsystems (delayed jobs, sphinx, caches etc.)?

Please note: Try to avoid proposing more than one solution. You just offload the decision to the developers you present this to, this is not nice. You are the person/group that analyzed this. You have everything at hand to decide now.

• If you cannot decide because you cannot foresee the consequences of your decision, research more
• If you have two competing solutions choose the one with less severe consequences
• If there are no foreseeable consequences to two competing solutions, propose the one you like more, the one that feels better to you.

Once you present this, the others will tell you if they know/foresee something you have not. Then we can adapt.