Software professionals have come up with a lot of great metaphors about what software actually is. Some people believe that software is like a castle that needs constant maintenance, others think about software as a garden that needs care and careful cultivation.
At GitLab we believe that software might be more complex than that, and that software is more similar to life itself.
Because of that it needs to adapt and evolve, usually through iteration.
As software products grow, become more complex, and get more widely used, things that were working well on a small scale, might not be sufficient on a much bigger scale.
Architecture Evolution Coachon the team page, someone who works on the level close to the Engineering Leader who is going to be the decision maker,
The author of a proposal and their Engineering Manager collaborate together to find people that will be amplifiers of their influence:
During the process of working on the proposal, the author will collaborate with an Architecture Evolution Coach and, optionally, a Domain Expert to create a blueprint of the change. The blueprint merge request will be then either approved or rejected by an Engineering Leader.
In order to choose the right people, the author and their manager first need to understand what is the scope of their proposal, what departments and teams will need to help to get the work done and how important it is for the organization.
The first step is to find an Engineering Leader that will be responsible for approving the proposal and merging the blueprint merge request. The Engineering Leader needs to be someone who works on an appropriate level in the organization to carry on the vision described in the proposal. For example, changes that involve only one team can be approved by an Engineering Manager, multiple teams within a one section - a Director of Engineering, but changes that span more than one department might require approval from a Executive VP or CEO.
Understanding who is the decision maker will make it easier to find an Architecture Evolution Coach because the best Architecture Evolution Coach will be someone who works on the level that is closest to the level of the Engineering Leader who is the decision maker (see the diagram above).
Domain Expert is someone who knows most about the topic and this person can work on any level in the organization, it even can be the author themself.
Once the blueprint of the proposal gets approved and merged, DRIs will be assigned to carry on the vision and coordinate work required to get it done.
All these people are here to amplify the influence of the author of the proposal in an environment that fosters creativity and knowledge sharing.
Architecture Evolution Coach is an expertise assigned to team members, visible on their profiles on the team page.
All Engineering Fellows and Distinguished Engineers are Architecture Evolution Coaches by default.
The purpose of involving a coach in the process of creating a blueprint is to allow people that know most about GitLab to share their knowledge and perspective on introducing complex architectural changes. This makes it easier to avoid the cost of working on the wrong thing, iterating improperly and fosters knowledge sharing.
Domain Expert Engineer is an engineering role at GitLab held by team members that are engineers with a deep experience in a particular area.
A Domain Expert is an engineer, usually an Individual Contributor, who knows most about a codebase and a domain in the area of proposed changes, but might still lack the deep understanding of the process behind introducing complex architectural changes, hence the collaboration between a Domain Expert and an Architecture Evolution Coach might be very useful.
Sometimes there is an Architecture Evolution Coach available who is also a Domain Expert in a particular area. In that case there is no need to involve another person.
Anyone can open an issue about a change they believe we should work on.
It can be a complex backstage improvement, an architectural change, a productivity improvement, or an efficiency improvement. It can be anything else that is too complex for a single individual contributor to handle.
Although we usually prefer starting with a merge requests, in case of complex changes like that, a merge request might not be something that is actionable, so we usually start with an issue.
Creating an issue is easier and less visible, it is an additional step before creating a draft merge request that helps to overcome anxiety related to speaking up and proposing big improvements. It is easier to capture ideas in issues than to create a merge request with a blueprint of a solution.
Then author of the issue loops an Architecture Evolution Coach and a Domain Expert in and they collaborate together to create a blueprint merge request. Collaboration between the coaches and a person who had an idea ensures that only proposals that that are achievable get described in a blueprint merge request. This makes it also easier to avoid the cost of iterating on the product architecture improperly and fosters knowledge sharing.
A blueprint merge request is a description of Why, How and What of the change that has been proposed in the issue.
A blueprint merge request gets created and made visible as a result of collaboration between an Architecture Evolution Coach, a Domain Expert and a person who had an idea. The author and coaches also need to be mentioned in the blueprint.
It needs to be written as a Markdown page in the
handbook/engineering/architecture/blueprints directory in
It describes the goal of the change and the 1-year landscape of how to make it happen.
At this point there is a blueprint merge request present in
project, but it only describes the 1-year landscape. It is not precise enough
to reason about how to get it done, how to iterate wisely to get the most of
People that got involved into the discussion in the blueprint merge request collaborate together to extend it with a 3-months landscape. More Domain Experts get involved if necessary. The result of this collaboration could be a description of three first iterations that can be done in a one milestone each. These iterations need to be a two-way-door solutions with a measurable impact.
If it is not possible to find at least two iterations, the blueprint merge request can not be approved and merged.
Once the iterations are described, in the merge request, the blueprint needs to get assign to an Engineering Leader for approval and merge.
The blueprint merge request needs to be approved and merged by the Engineering Leader who has been chosen as a final decision maker.
The choice of the leader depends on the extent of proposed changes, the area that the changes are supposed to be applied to and perceived cost of this architectural change.
Organization structure chart can be useful to determine who the Engineering Leader could be.
Once the merge request gets merged, the Engineering Leader who merged the proposal collaborates with people involved to find Directly Responsible Individuals who will be decision makers from now on and will be responsible for the progress.
The blueprint needs three people that will become DRIs:
The Engineering Leader who approved the proposal can become an Engineer Lead DRI, but they can also delegate this to someone else. It is important to choose people taking their area of interest and responsibility into account and the "How" description that depends on where the proposed change needs to happen, who knows the most about particular area of the product, service, and codebase.
Then DRIs will propagate the blueprint downstream, to respective teams that will need to be involved, and these teams will schedule the work based on their interpretation of 1-year landscape and proposed iterations that will happen in the next 3 months. If a Working Groups gets formed the list of DRIs can be extended according to the process of how Working Groups organize efforts around the work.
DRIs can decide to form a Working Group to structure the efforts related to the architecture change better, but whether a Working Group should be formed or not depends on the size of the change and if forming a Working Group actually makes sense in this particular case.
The concept of a Working Groups can be an extension of the Architecture Evolution Workflow, but if it is not applicable in a particular case, a different process can be followed, like the suggested one that is described below.
After the iterations described in the blueprint are done, the work can be extended to the next three iterations and the blueprint needs to be updated.
Alternatively the work can be concluded and the blueprint needs to be updated with results / outcomes.