Article summary
If your team hasn’t yet reached the utopia of a fully automated deployment pipeline, you likely have a series of steps or scripts that you perform for every deployment. Perhaps this process is documented somewhere, or maybe (more likely) it’s just passed down from developer to developer through tribal knowledge.
I’m currently working on a team like this. We have a document in our internal wiki that loosely describes the steps to perform at the end of every sprint. These steps help us move from a local repository to releasing build artifacts to our client. It is not a complicated process. It takes roughly half an hour, and it works perfectly 99% of the time. We are in our comfort zone, with nothing pressing us to change processes or investigate beyond our typical routine.
However, as we approach our first public production release, our client recently contracted with a third-party team to run a mock deployment that follows many regulatory specifications and formally documents the process. For the first time, deployment was out of our hands, threatening our comfort zone.
Documentation
The first lesson we learned through this process was that our documentation and configurations were muddled and even outdated in spots. As the outside team started digging through our codebase, we received several emails asking, “Why is this dependency not building?” or “What is this environment variable for?” or “Where are the configuration details for this service?”
As a team, we had maintained what was being used and knew how to find information that we needed regularly. However, some of these dependencies and configurations had not received much attention after setup. As they were being dusted off for someone else, we recognized how long that had been. We also realized that these kinds of issues could be resolved by simply taking the time to refamiliarize ourselves with our documents and updating them as needed.
Environment Configuration
The second lesson was that we needed to learn more about our tools and development environment. Up until this point, every member of the team had been developing in OSx with a finely-tuned set of environment variables, libraries, and configurations.
As we passed our deployment process on to a new team who had not gone through our typical onboarding setup, we realized the importance of the environment. Differences between OSx and Windows wreaked havoc on our scripts. Some of our OSx-specific tools had to be replaced by Windows counterparts that worked just slightly differently.
When we were informed that the team did not want to use Docker, we had to discover how to replace our PostgreSQL container in a new environment. The tools we had been taking for granted suddenly needed to be switched to less powerful, unfamiliar options.
Solving these problems was slightly more difficult because it required us to restart from square one and find new solutions to old problems. Taking time earlier in the process to understand what each tool and script is accomplishing would help to alleviate these kinds of issues in the future.
The Deployment Pipeline
Personally, this experience taught me a lot about the deployment pipeline. When I had been responsible for deploying the app, I had typically just gone through the documented process, verified that builds got released properly, and moved on. I never really stopped to think about what each step was doing.
Working outside of my comfort zone forced me to set aside the routine, consider the objective of each step, and then decide how to get to that point. Partnering with an outside team to set up a new environment gave me a chance to focus on what is really happening in our deployment pipeline. It was a frustrating process at times, but I believe the experience has made me a more well-rounded developer.
Lessons Learned
This was a valuable experience for both myself and the team. We learned the importance of documentation, especially for pieces of the codebase that aren’t used regularly. We learned about the fine-tuned environment that we had set up. And I learned all about what our deployment pipeline was accomplishing at each step.
While I don’t think it’s always possible to have a third party audit your processes, this opportunity still presents an important lesson in perspective. You may be able to gain insight into your codebase by considering how someone who is completely unfamiliar with the project would interact with it.