Unravelling the Code Tapestry: Documenting Final Steps Before Implementing Changes

  • Friday, Apr 12, 2024
An extreme close up of an Apple Magic Mouse 2. The mouse is oriented such that we are looking at it's side and we can see an out of focus keyboard next to it. They are both placed on white a desk.

The cover image for this post is by Sigmund

This is part eight in our series of blog posts detailing our system for genius when working safely with legacy code. The other parts of this series include:

  1. A Series On Safely Navigating Software’s Timeless Artifacts
  2. Preparing To Tame Legacy Code With User-Led Odysseys
  3. Conversations with Code Custodians
  4. Why Documentation is Key to Legacy Code Success
  5. Before Running the Build
  6. Documenting your Progress
  7. Accessing a Development Database for Local Testing
  8. Learning the Release Process and PR Strategy

Introduction

In this part of our series, we will delve deeper into the final steps required before making changes to a legacy codebase. We will cover submitting a PR for documentation, running automated tests, performing manual testing, and understanding any current issues with the codebase.

Understanding Release Process and PR Strategy

We spoke about this in the previous part of this series, but here’s a quick reminder of why: Before implementing any changes, it is crucial to familiarize yourself with the project’s release process, including how PRs are handled within the team. This will help you understand how your code updates should be structured and submitted for integration into the main branch. Familiarity with the team’s workflow and best practices will make it easier for others to review, merge, and maintain the changes in the future.

Submit a PR for Documentation

Once you are familiar with the release process and PR strategy (as we discussed in the previous post in this series), it is crucial to update your documentation repo (explained in part 6 of this series) to accurately reflect the release process and PR strategy. This ensures that everyone working on the codebase has access to the most recent information and guidelines. It is essential to collaborate with teammates or users during this step, as their input can be invaluable in maintaining consistency across the project.

Once you have thoroughly updated all documentation, submit a pull request for the documentation repo. In this PR, it is important to be explicit about any changes made to the documentation and how they relate to the existing workflow.

This collaboration with teammates or users will help create a comprehensive and easily accessible documentation resource for all contributors and maintainers of the project. Once the PR has been reviewed, merged, and implemented, it will greatly improve the overall efficiency and organization of the legacy codebase.

Running Automated Tests

Before implementing any changes, it is essential to run all existing automated tests to ensure they are passing. By doing so, you will be able to identify potential issues that could arise from your proposed updates and mitigate them beforehand. This step not only minimizes the chances of negative impacts on the codebase but also helps maintain its stability and smooth integration process.

During this stage, it is crucial to document any tests that fail, as this information will help assess the impact of the changes on the existing functionality. Analysing these test results will provide valuable insights into the project’s current state and how your updates could affect it. This proactive approach ensures that the codebase remains stable and functional throughout the implementation process.

After running automated tests and identifying potential issues, you should address them by adding cards (or task items) to the backlog for the code base. This will ensure that the potential issues are logged somewhere, and that decision makers are able to assign the time and budget to deal with them.

Performing Manual Testing

After running automated tests, it is essential to perform manual testing to verify the accuracy of your notes and test results. By manually confirming the system’s performance and behaviour, you can identify and address any issues that may arise before integrating your changes into the main branch.

Manual testing involves examining various aspects of the codebase, such as user interactions, workflows, and overall system responsiveness. It is important to maintain open communication with teammates during this process, as their insights can help ensure a thorough assessment of the system’s performance. If possible, have a real users of the system guide you through their workflow. This will help you to ensure that everything is up and running as expected—it will also allow you to discuss any pain-points or issues that the user has, too.

As with the automatic testing, you should document any issues encountered (as cards or tasks on the backlog), as well as their potential impacts on existing functionality.

In Conclusion

In conclusion, it is crucial to submit documentation PRs, run automated tests, and perform manual testing before making any alterations in a legacy codebase. By following these final steps, developers can work safely within the codebase while maintaining stability and functionality, paving the way for a smoother integration process for future contributions.

If you’d like us to help you work through the challenges involved with working safely with a legacy codebase, either in a hands-on capacity or as a consultant, get in touch with the form below

We'll never share your name with anyone else.
We'll never share your email with anyone else.
Providing a subject can help us deal with your request sooner.
Please be as specific as possible; it will help us to provide a more specific response.
Un-checking this box will ensure that your data is deleted (in line with our privacy policy after we have dealt with your request. Leaving this box checked will auto enrol you into our email communications, which are used for marketing purposes only.