Introducing Large-Scale Tooling Changes: A Software Engineering Guide

As software engineering organizations evolve, introducing new tooling changes can have a significant impact on long-term productivity, collaboration, and overall code quality. This is also not an easy task in many ways.

Recently, at Salesloft, I had the opportunity to lead such an initiative: integrating Knip, a dependency management and automated unused code removal tool, in our main front-end application monorepo. This guide comes directly from that project. I will walk you through a step-by-step process for introducing large-scale tooling changes in software engineering projects.

Before we begin, here's an important note: The approach in this document is quite general and should work with different tools and situations. However, when adding new tools, it's crucial to think about the specific needs of your project and team. While it's usually better to introduce tools gradually, some can fit smoothly into existing workflows all at once.

Step 1 — Evaluate the tool

Before adding any new tool, it's important to check what it can do, what it can't do, and how it might affect your project.

• Assess the tool's main function. Understand what the tool is meant to do and how it fits with your team's goals. If possible, give it a try.

• Research the tool's ecosystem. Look into the tool's community, documentation, and existing integrations to understand its maturity and the level of maintenance and support.

• Evaluate the tool's compatibility. Check if the tool works well with your project's current setup, including the infrastructure, programming languages, and libraries.

• Estimate the costs. Think about the cost of migration, possible pitfalls, and, eventually, sunsetting of the tool.

• Look into the license. Check the tool’s license and to what extent it can be used.

• Compare alternatives. See if there are other tools that can fully or partially solve the same problem. If there are, compare them and decide which one is the best fit for your situation.

• Consider integration options. Describe the different ways you could integrate the tool.

Step 2 — Start a discussion

Once you evaluate the tool yourself, it's time to see if the team is also interested and gather their feedback — this is the next step in evaluating the tool. You have a few options here—the choice depends on how simple or complex the tool is. As the complexity increases, you might choose a more formal approach.

Here are two example approaches you can take:

• Informal: Create an open Slack discussion channel to share ideas and get feedback.

• Formal: Create a Request For Change (RFC) document that explains the proposed tool change, its benefits, and possible risks.

No matter which option you choose, you should focus on a few key areas.

• Collect feedback. Encourage team members to review, comment on, and give their input. Tag the right people and set a deadline for collecting feedback (e.g., two weeks), to make sure you get input on time.

• Get approvals. Get the necessary approvals for the tool (architecture, security, etc.).

• Describe the integration path. Decide how you will integrate the tool and explain the method in detail.

• Communicate with the teams involved. Communicate and discuss what is needed from other delivery teams.

Step 3 — Integrate the tool into the repository

Once the tool change is approved, it's time to add it to your repositories.

• Install the tool. Install the tool, which may involve creating a new service or module in your repository to accommodate it.

• Add minimal configuration. Add the appropriate configuration and necessary scripts.

• Focus on local development experience. Ensure the tool is available locally for other engineers first, and save any automation for later. This allows engineers to start using the tool if they choose and provide feedback.

• Communicate the change. Communicate the change introduced to the team, along with the next steps, to keep everyone in the loop.

Step 4 — Run as a part of automation

Integrating the new tool with your Continuous Integration (CI) pipeline is the next crucial step to ensure the tool is effective.

• Integrate into a workflow. Add the tool to the appropriate part of the workflow. Make sure it runs on every pull request, unless that's not practical.

• Add a minimal low-severity ruleset. Start with a basic set of useful rules and add more later. Initially, it might be appropriate to make the workflow step non-blocking by using warnings instead of errors. This approach allows more people to notice the tool without interrupting ongoing development. For pull requests, consider running the tool only on changed files at first, and then expand later.

• Highlight results. For pull requests, make sure the results are highlighted, especially when they are non-blocking. You can add them as comments on pull requests because warnings in a successful pipeline will almost certainly be overlooked.

• Communicate the change. As always, communicate the change to the team.

Step 5 — Add documentation

Make sure to include all the important details in the documentation. You can do this during the earlier steps, but it's also fine to create it now, once the basic setup is complete. Any needed context can be understood from the initial discussion.

• Update the changelog. Add a changelog entry if your repository maintains one.

• Create documentation. Make sure to cover most of the following aspects.

  • Short description of the tool and its purpose.

  • The reason for introducing the tool.

  • Common CLI commands (if the tool supports them).

  • Guide to using the tool.

  • Description of the CI workflow integration.

  • Links to official documentation or other related resources.

• Communicate the change. At this point, you most likely know what to do.

Step 6 — Spread the word

After introducing the tool change with clear documentation, share your experience and get feedback from the wider team. It's usually a good idea to have a short meeting to discuss the tool with anyone whose work will be directly affected by it.

• Describe the “why”. Explain the tool's function and the reason for its use.

• Show it in action. Prepare a demo to show engineers how to use the tool. Use the documentation and other relevant resources as needed.

• Highlight automation. Explain how the workflow integration works and how it affects engineers.

• Keep a record for future reference. Record the meeting for future reference. Share the slides and the recorded meeting in the appropriate channels.

Step 7 — Involve other teams in actively adopting the tool

If introducing the tool requires action from other teams (to handle the results or integrate the solution into their areas), be sure to involve them. Depending on what you can realistically handle yourself and how you define code ownership, this step will need varying amounts of convincing and persuasion.

Here are two example strategies you might follow.

• Start and hand off. Consider starting the work for other teams and then passing it on to them.

• Do it yourself. Alternatively, if the change is simple, you can do all the work for other teams and then pass it on to them just for review and testing.

Step 8 — Refine the configuration and expand the rules

As the repository evolves and engineers start using the tool, we should continue to refine the configuration and consider expanding the rules.

• Expand the ruleset. Consider making the rules stricter or adding new rules.

• Run on all files. Think about changing the workflow to apply to all files, not just the ones that have been changed.

• Block CI. Consider blocking the workflow step by changing warnings to errors (only do this if it won't create too much friction in pull requests).

Note: This is the final, ongoing state.

Conclusion

That's it! Introducing large-scale tooling changes in software projects can be overwhelming. It involves not only doing the work but also getting everyone on the same page. No matter what tool you introduce, there are a few key areas and common themes to focus on.

• Evaluate and research. Before integrating any tool, carefully check its features, limits, and how it fits with your current systems. Doing this early work helps avoid problems later and makes sure the tool meets your team's goals.

• Take small steps. Make changes gradually, starting with local access and non-blocking automation. This helps engineers slowly get used to the changes and give feedback, reducing interruptions to ongoing development.

• Over-communicate. Consistent and clear communication is very important during the whole process. Keep everyone informed about changes, collect feedback, and explain why the new tool is being used.

• Get everyone involved. Encourage teamwork by including the team in talks and decisions from the start. Their feedback and support are crucial for successful adoption and lasting impact.

If you enjoyed the article or have a question, feel free to reach out to me on Bluesky or leave a comment here! 👋

Further reading and references

• Photo by AJ Robbie on Unsplash