Despite having worked on various parts of Review Board for several years, the distinction between a ReviewRequest and ReviewRequestDraft has often been a bit blurry for me. I’ve had the occasion recently to explore the relationship between these two models, and I wanted to write it down for future code-spelunkers.
The way I want to explain this is by exploring the lifetime of a ReviewRequest, from cradle to grave. So, let’s get started.
When a ReviewRequest is first created, it has barely information in any of its fields, and the public attribute is set to false. When the user starts making modifications to a Review Request though, a Review Request Draft is then created. The changes that the user makes after creating the initial Review Request actually update the Review Request Draft instead. Even if the Description and Testing Done fields have been populated, that information is not in the ReviewRequest: all fields are set on the ReviewRequestDraft.
When the user clicks “Publish” on a review request page, the information in a ReviewRequestDraft is dumped into the ReviewRequest model. The ReviewRequestDraft model is deleted, and the state on the ReviewRequest is set to public. Congratulations, your review request is now visible!
Suppose now you want to make a change to a review request. Perhaps you’ve updated the Testing Done field, or you’re adding a new reviewer to it, or you’re changing the summary. What happens is that a new ReviewRequestDraft is created for the ReviewRequest, with a copy of all of the current fields in the ReviewRequest, and any changes you make go into that ReviewRequestDraft.
So when you, or anybody who has mutation-privledges for a ReviewRequest sees the review request page, and a ReviewRequestDraft exists, you see the information in the ReviewRequestDraft. For anybody without mutation-privledges looking at the page, they see the unchanged ReviewRequest data.
When it comes time to publish the draft, the changes in the ReviewRequestDraft get, again, dumped into the ReviewRequest (a ChangeDescription is also created in order to document the changes being made to the ReviewRequest) and the ReviewRequestDraft is destroyed.
When a ReviewRequest is marked submitted or discarded, that state change occurs on the ReviewRequest, and ReviewRequestDraft does not need to be created.
So that’s how changes occur on ReviewRequests.
Review Board Student Blog 