This is part 3 of the Disciplined Engineering series. It is for teams that have an established engineering process with confidence around the quality of their application. This article will help improve your engineering game by identifying the common patterns that will further improve your team’s focus on quality. If you don’t have an established culture of engineering at your company, we recommend reading Part 1: Building an Engineering Process. If you would like to be more confident in your code, we recommend reading Part 2: Creating Code Confidence.
Refining Your Engineering Process
Teams that have a well-established engineering process with a mature set of tools to support the quality of their application are ready to start refining their process. At this point, new practices can be added that accelerate development by allowing engineers to cleanly focus on solving problems or implementing features using standard patterns.
While all of these practices are capable of improving your engineering process, they will be most effective after your organization has gone through building an engineering process and can confidently and consistently release new features. These recommendations are aimed at teams that are ready to further improve their engineering process. They are topics that SitePen most often helps mature teams to address as they further refine their process.
Build an Onboarding Process
An onboarding process is a documented set of tasks and information necessary for a new member of the team to begin contributing to the project. By defining an onboarding process it forces the team to make sure they have documented all of the necessary steps and decisions for building and working with the application. Teams without a well-defined way to ramp up a new member surely have undocumented, institutional knowledge that is negatively affecting their organization. In many ways, building an onboarding process is a litmus test for the health of your project.
A good onboarding process should cover topics necessary for a new developer to contribute to a project. These topics should already exist as part of the team’s central document repository that we discussed in Building Shared Knowledge from Part 1 of this series. It should provide answers to standard questions regarding your tooling, processes, and high-level architecture. Common questions for a new team member include:
- How do you locally build and deploy the application?
- How do you debug the application?
- What tools and plugins are we using?
- What is our engineering process?
- How does a feature progress from idea to production? (i.e. defining done)
- What is the high-level architecture of the application?
Even if your team never adds a new member to the team, documenting an onboarding process will help to clearly define the project. A member of the team should be able to go through the onboarding process and ensure that the process is reproducible and correct. This is especially important to do well before a new team member is added. Teams without a good onboarding experience will find it very difficult to add additional engineering resources when they need them the most! This is why SitePen puts so much emphasis on updating our client’s onboarding processes for each project we join.
Have a Release-first Approach
The biggest and most common show-stopper from engineering is not having a release process in place to deploy the application to production. It is understandable how so many teams get in this predicament. The natural focus for most projects is building an application with some new and exciting set of features. While a release to production is a non-functional requirement that typically comes at the end of a project. However, while many Agile projects have a defined set of features that make up a release, it is all too common for product owners to decide to truncate a set of features and release early.
Engineering teams should plan for release at the onset of any project in order to avoid becoming a blocker. At its most basic level, the release process should be documented as well as the roles and responsibilities of individuals involved in the release. The engineering team should also ensure that the master branch is always in a state that is ready to ship to production. Often this means having a system in place that allows for incomplete features or features slated for a future release to be turned off or hidden. Finally, the release process should be automated as much as possible so it is well-known and repeatable and always deploys exactly the set of services necessary for your application.
Defining the release process and putting systems in place to support it should be the number one priority of the lead. Once a project has a release process you can release any time your PM and PO agree the product is ready to go to production. Making sure that this process exists first puts the team in the best possible position and is a marker of a mature engineering process.
Git Process
On large applications, it’s important to have a source control process in place. By using GitHub at SitePen, we ensure that each engineer works from their own fork and creates a feature branch for each feature they work on. When their work is complete, they raise a pull request (PR) back to the master fork. The pull request itself uses a template that asks the engineer about the type of change they’re submitting, that they have linked to any associated tickets, and often includes a checklist of things we want every PR to include. This helps to support our engineers by reducing the number of things we have to remember and it makes sure our PRs follow the same process and standards. Once submitted, a number of processes are spun up that build and test the code, check for code coverage, and automatically deploy the project for review. This serves to best inform the person reviewing the code and provide them with quality metrics so that they can quickly and efficiently review the code.
This process works well for us as it ensures that each task is worked on individually with minimal conflict from the features being worked on elsewhere. When the code is ready, the submitter reaches out and requests another engineer for a code review.
The code review process is a good indicator of whether or not a team has a healthy engineering process. In general, any member of a team should be able to perform a code review and PRs should not linger for more than a day without a review. Teams best able to achieve this are ones with few single points of failure, have taken the time to document and share knowledge, and have automated processes in place that support good engineering practices. Teams should also be using this time to ensure that tests are well written and strictly define the problem space as a way to maintain quality.
Managing Bugs
Bugs are an inevitable part of any project. Mature teams should have a well-defined way of triaging and fixing bugs as part of their engineering process. The first step in dealing with any bug is communicating exactly what the problem is and the expected outcome. A template should be created that asks for all of the important information for reproducing the problem. Common pieces of information include
- Step-by-step instructions for reproducing the bug
- Information about the environment including the browser, OS, timezone and any other information agreed upon by the team
- The expected outcome or behavior
- The actual outcome or behavior
- A screenshot or a video of the bug
All of this information helps to capture the state of the application as well as provide some insight into the importance and complexity of the bug. This is helpful in deciding how to triage a bug, which involves balancing its severity and the effort to fix it against other features.
Once an engineer starts work on fixing a bug their first step will be to reproduce the issue. This is a necessary step in isolating the section of code responsible for causing the bug. As an engineer fixes a bug, one or more tests should be written to verify the fix and ensure the same issues cannot happen again.
Conclusion
In order to continually improve your engineering process, it is important to find ways of creating feedback. Mature teams add processes to address deficiencies experienced by the team and rely on metrics, both objective and subjective, to evaluate their effectiveness. In other words, it is not beneficial to add a process unless its benefits are well understood by the entire team.
SitePen has helped numerous teams build and refine their engineering processes. Establishing a positive feedback loop that encourages self-evaluation and improvement is the most important step in building a good foundation. That requires a solid understanding of when and why these processes are put into place in order to progressively improve quality and outcomes. If you find yourself looking for ways to improve your team’s engineering culture you’ll find no better partner than with SitePen. Please contact us if you’d like to discuss what SitePen can do to help!