Developer Workspaces
Effective Main Line (or Trunk Based) development starts in the developer workspace.
The goal of Mainline development is for teams to be able to deliver features with fewer distractions and more productively. One of the things that enables working on a Main Line to work is having a reliable Developer Workspace —the environment that you need to develop code.
A well-set-up workspace improves individual and team productivity by:
Making it easy for developers to contribute to the code base when they join a team or organization.
Ensuring that everyone gets the same results in every environment, including in the Continuous Integration (CI) system.
Reducing the cognitive overhead of the setup process, and thus the chance for error.
Many teams take Developer Workspaces for granted. While a skilled developer can set up a workspace with minimal guidance and tooling, bespoke setups are error-prone. Improving workspace setup is an easy way to improve the reliability of your Main Line process.
A Workspace and Its Qualities
A Developer workspace is everything you need to contribute to a software module. This includes:
The code.
Code dependencies, such as libraries.
Development Language Environment.
Build tools.
Build processes and scripts.
Some of these are straightforward to specify and to keep up to date:
Code comes from a source code repository.
Most language environments have mechanisms for specifying dependencies.
Build Tool versions can be managed by wrapper scripts, though some might involve extra work.
Some are a bit more nuanced:
Language environments vary in how they manage installation and version management.
Build scripts should execute consistent steps across environments, enabling developers to get results that are consistent with what other developers might see and with a CI environment.
A good developer workspace means having what you need to build and test consistently.
How to set up a workspace (tools)
At its simplest, a workspace setup could be a document that has steps like:
Install your SCM tool (git, for example)
Check out a specific repository
Follow the instructions in the README file to set up everything else to build and test
Run the following steps during your build and test cycle
Documentation can get out of sync with practice, so you want to add some automation, but a checklist or script is an important first step in deciding what to automate and how. A setup document can evolve from words to executable documentation:
Start with descriptive steps (install this tool)
Add command lines to execute ( run brew install …)
Combine the commands into a single script that executes multiple steps.
The end result can be a process doc that includes a minimal number of manual steps that guide the user toward which scripts to run.
Build Lifecycle Process
Since the goal of a developer workspace is to ensure consistent build results across environments, the build lifecycle process is also a key part of a workspace. Having the correct tools isn’t sufficient to avoid “works on my machine” scenarios if the definition of “works” varies from person to person. You want an easy way to run the same processes as are run in CI.
Some tools (like Maven or Gradle) have standard lifecycle stages (Build, check, test etc) that are fully specified by the build scripts and fairly standard. For these, you execute the build phase in every environment. For others, you may run individual commands. To make it easy to execute the build Lifecycle in a consistent manner, you can use a tool like make to provide targets that can be used both in the workspace and your CI script (Jenkins, GHA, etc.).
Given that there are some small differences between a CI environment and a developer machine, there might be some differences, but you can generally address those by having a thin layer that runs only on a developer machine, which might do some basic setup. Ultimately, the developer should be able to run the same target that CI runs, whether it’s gradle build or make pipeline.
Productizing Your Installation
Since the workspace setup process will be something every team member depends on, you want to treat the setup script as application code (or at least a supported tool). This means that it :
Is Maintainable: The script will potentially be used by every team member, and errors in the script will lead to unnecessary wasted time by team members.
Has a Defined scope: It’s OK that the script doesn’t work in all cases as long as you understand the cost/benefit ratio of a decision not to support a scenario.
It’s OK to defer adding functionality if the functionality isn’t widely needed or if there are reliable workarounds; it’s better to have a reliable tool that people use and want to use than a very fully featured one that is dysfunctional.
Keep any process you use up to date by encouraging team members to use it periodically to create clean workspaces or to refresh existing ones.
An enabling developer productivity team can help start the process, but in the long term, developers should own the workspace set-up script because they understand the technical requirements of their application (and their process) best. Different teams might have different processes, but each can leverage common tools and approaches.
What about customizations?
Some developers might prefer to use tools that don’t match those in setup automation. As long as you have a way to verify that a consistent environment exists, you don’t need to be dogmatic about using the tools as long as you acknowledge that any custom processes can be treated as “unsupported”: if team members have time to help someone using a bespoke process, they can, but the default is to “try the standard way.”
Experimentation gives teams a way to discover ways to improve the process. And if the “standard” way frustrates team members enough that they choose not to use it more often than not, you need to consider addressing those issues.
How Identical?
The approach described here standardizes the elements of a developer workspace above the Operating System layer, focusing on:
Common versions of tools
Common execution steps.
That works well enough in many cases. If you develop on a Mac but deploy on Linux, the tradeoff between consistency and the usability of IDEs and other developer productivity tools is often worth it.
You could also build container images to fully standardize the development environment and use the exact same image for local development, CI, and deployment, but this approach can add overhead and make using tools such as IDEs a bit challenging. If you discover that errors occur because of an OS-level inconsistency, check to see if that is essential or accidental. More often than not, standardizing tools and their versions will address most of your issues. If not, incorporating more standardization is also an option, but be wary of unforeseen productivity costs related to the options the standardization removes.
Closing Thoughts
Putting a little bit of thought into how to set up a workspace can help improve the efficiency and quality of the onboarding experience for everyone on the team, and productivity in general. Even if “1-click” automation seems intractable now, a clear, easy-to-follow script document can form the basis for automation that you can incrementally develop.