Documentation: Request for Comments
A few weeks ago I talked internally at Candyspace about how documentation is playing a big part in the Android team and how we evolved after introducing different kinds of documentation into our development process.
When introducing a new feature into the app, we usually create a separate git branch for the feature and proceed with its implementation. When the implementation is complete, a new pull request is opened against the main branch and a review is requested from at least on colleague before it gets merged.
Figure 1: Initial development timeline
However, in some features (or bug fixes) there were times when the reviewer would suggest a “better” solution or simply didn’t like the approach, to the problem that we were trying to solve, which resulted in frustration and a bittersweet feeling from the developer that was implementing it due to the time wasted.
In this blog post I would like to share how we incorporated RFC’s (Request for Comments) documents to better architect what we are about to implement. Even though RFCs have a lot of benefits, the main reasons why we write them are the following:
- All team members can comment on a new change/feature before it gets implemented;
- It serves as an historical report (even across teams) of the decisions taken at the time and the context in which they were taken and not lost in emails or chats;
- In the long run, it removes the dependency to another colleague’s knowledge of the product you are working on.
When looking for examples, we found Rust’s rfc’s repository that describes an exceptional model that is being used to develop the language. If you read through the whole process, you may come to realise that it seems too long and strict but it’s important to understand that Rust is an open source language, with thousands of contributors and not the average team.
Since our team is much smaller and we work on a mobile app, we adapted the template and modified our development current process with what we consider valuable for us.
Figure 2: Development timeline
So our current process includes the writing of an RFC document and a discussion of the solution in a dedicated pull request, before the implementation takes place.
Figure 3: Branching timeline
This means that besides the usual feature branch, we now create an extra branch for the RFC where we will write the document that will get merged to the main branch as soon as its implementation is ready.
But a successful discussion can only happen if all team members follow a simple set of rules in order to keep the discussion updated and organised. After analysing what went wrong in the past and how could we prevent it in the future, this is what we agreed works best for us:
- Create a dedicated branch for the RFC;
- Create a markdown file with all the required information by following the template, inside a folder that will only contain RFCs;
- Create a PR (pull request) against the main branch with the RFC document. Assign a review tag in that PR;
- A discussion will take place in the RFC’s PR until at least 2 colleagues approve it, by assigning their user tags in the PR (ex: Jakob, Tiago);
- After the approval, the process ends its design phase and the feature enters in the implementation phase;
- The RFC’s PR should stay open, with the in development tag assigned, until the feature’s implementation is merged into the main branch;
- If questions/suggestion arises during implementation, the question tag should be assigned to the RFC’s PR, which can trigger an update to the RFC. If the question/suggestion is addressed, the question tag should be removed;
- If a new solution arises during implementation by any team member, only the main developer can decide if he will push it back to design phase or continue with the implementation;
- When implementation finishes, the feature can be code reviewed and then merged into the main branch, together with the RFC’s PR. Make sure the RFC’s PR only contains the tags with the names of the colleagues that approved the RFC.
Figure 4: An example of an RFC’s Pull Request timeline
Feel free to use it and adapt it to your own context. If in the long run, you felt it helped you and your team, please reach out to me and let me know about your experience!