The Code Etymologist is a multi-part series that covers typical software knowledge that deserves to be documented and shared within development teams.
- Preface
- Part 1: Project setup
- Part 2: Coding guidelines
- Part 3: Development workflows
- Part 4: Product requirements
- Part 5: UI Components library
- Part 6: Data structures
- Part 7: Technical decisions
- Closing thoughts
Having the project running locally and knowing the coding guidelines, we can start writting some code. But software development is not only about writting the code, but delivering it to our end-users, which include multiple steps and various workflows.
Unless we're explicitly handling only certain parts of the entire software lifecycle, we need to understand how to get the code from our local computer to the final client.
Next, we'll cover some typical workflows that deserve to be well-documented and available to all team members involved in the development lifecycle.
Branching strategy
Before working on any task, we must know how to use the Version Control System, in case there is such a system implemented. There are multiple strategies for using branches: Git Flow, GitLab Flow, Github Flow, Trunk-based development, Forking workflow, etc.
If the team uses exactly one of the well-known and documented strategies, it's sufficient to simply mention it and link to its detailed documentation.
The original Git Flow diagram, proposed by Vincent Driessen in 2010
However, if the team uses a customized strategy, simpler or more complex, or with different branch names, it's important to document all these details.
The The Fluid powered TYPO3 Git workflow
Code reviews
There are various reasons to submit code for review. While some teams use code reviews as an optional practice to encourage knowledge sharing, others enforce code review as part of their integration workflow to supervise and control what gets merged into the main repository.
Some code review flows might be pretty simple and somewhat linear, like the one from Holistics. One thing I'd like to highlight in the diagram below is the separation between internal and external actions, to easily understand where each of them takes place.
But code reviews could get really complex, involving different validation levels from different roles. One such example is the pull request review process from Red Hat KIE/BA. Notice the visual separation of actions, using different colors for each role involved.
Task lifecycle
Each development teams have its own tasks workflow. Since most team members will be working with tasks and tickets, no matter what software is used for issue tracking, it's important to have a clearly defined lifecycle.
Below is a diagram of our internal workflow. It depincts all the states and possible transitions between them. This is helpful for engineering, design, testing, and product teams as well.
Release cycle
In case we have a well-defined release plan, it's crucial to have it recorded, so all people involved can refer to the same information. For instance, Node.js Foundation publicly shared their release lifecycle documentation, including the terminology and how Long Term Support works.
The schedule diagram displays how LTS applies only to even-numbered versions, not to odd-numbered versions. In addition, it's easy to see that each LTS lasts for 18 months, while Maintenance lasts for another 12 months. This diagram is also displayed on the Node.js Releases page, showing the actual versions.
In the end, the important take away is using images and drawings to communicate information. While written text offer a great level of details, visual diagrams provide a concise overview and an intuitive companion.
Continue reading Part 4: Product requirements