As any software development team can tell you, creating new releases of your software is no easy feat. Rather than just throwing the old version in a digital trashcan and moving on, creating new versions of your software requires several careful steps to transition smoothly into the future. However, what may seem like an unending gauntlet of red tape and needless bureaucracy is actually a set of checks and balances that help keep things from spiraling out of control. To that end, one of the most important elements for keeping a new release on track is documentation. Documentation not only helps other people understand what’s going on inside your code base, but also forces developers to think through all possible scenarios before releasing anything to the world.
What Does Documentation for a New Software Release Look Like?
For the most part, documentation for a new release is really whatever you decide it should be. However, the one thing that all new releases must include is a new set of manual tests. Manual tests are the one concrete piece that ties a new release to its previous version, while also ensuring that the new release actually works as intended. Admittedly, it’s not a perfect system. The one downside to manual tests is that they have a tendency to grow stale over time. If you don’t keep up with them as your software evolves, you risk losing sight of your core functionality. Fortunately, if you’re working in a test-driven environment, you can use testing as a check against stagnation.
Committing To New Manual Tests
Unlike the rest of the documentation work that goes into creating a new release, committing to a new set of manual tests is more of an all-hands-on-deck affair. After all, when you’re dealing with new versions of your software, you need to make sure that it works with every old manual test. However, it’s important to consider that not all manual tests are created equal. Some are better than others at accurately testing your software, while others might be better suited to testing something else entirely. For example, if you’re working with a system that generates a new user account on a first-come, first-served basis, you’d probably want to create a new manual test to ensure that first-come, first-served still works. However, if you’re working with a system that generates a new user account based on a lottery system, you probably don’t need a new manual test to make sure the lottery system works. Admittedly, this doesn’t solve the problem of how to choose which manual tests to keep and which to ditch, but it should help guide you towards a more informed solution.
Depending on how your software is written, and how often you release new versions of it, your dependencies may or may not need to be rebuilt every new release. However, if you want to ensure that your new release is compatible with every previous version, you’ll need to rebuild dependencies for each previous release. This can be a tedious process, but it’s an important one that helps your new release find its footing. For example, if you’re working on a new release of your software that uses a new third-party dependency, the third-party dependency needs to be rebuilt for each previous release.
Updating the Code Base
As mentioned above, you need to update your code base for each previous release. This is a necessary step so that your new release can link with each previous version’s dependencies. However, that’s not the only thing you need to update in your code base. You also need to update other bits of documentation, such as release notes, and you need to update your source code file structure. Release notes are one of the few pieces of documentation that is actually visible to your end users. After all, they’re the notes that pop up when you install your software and tell you what’s different about this new version. However, release notes are also one of the few pieces of documentation that you need to update on a regular basis. This is because they’re prone to a lot of the same pitfalls as user-facing documentation. As such, you need to update release notes for each new version of your software.
Merging and Resolving Discrepancies From Previous Releases
This is where things get a little more interesting. When you’re creating a new release, you get to make some of your own rules. As such, you also get to resolve discrepancies that arise from previous releases. For example, let’s say that you’ve created a new release of your software that runs on the latest version of Java. However, your previous release runs on Java version X. In this case, you could either keep the new release on the latest version of Java or you could keep the previous release on the old version of Java. However, you should keep in mind that these discrepancies don’t exist in a vacuum. They exist between previous releases of your software and your new release. So, if you keep the previous release on the old version of Java, you need to make sure that the discrepancy between the two releases is accounted for in your new release.
Committing Changes from Previous Release
At the end of the day, all of the above elements contribute to creating new functionality in your release. However, there are some elements that exist purely to keep your existing functionality intact. For example, you need to update any documentation that helps people consume your software, such as your user manuals. You also need to audit and update your test cases to account for any new functionality that was added to the new release. Finally, you need to commit any changes to your source code file structure and your build process.
At the end of the day, creating new releases of your software is an important part of any software development process. However, it’s also a delicate and complicated process that can quickly go off the rails if you don’t know what you’re doing. To that end, creating new releases requires a lot of careful documentation and a lot of careful decision-making. Thankfully, this process is a two-way street. While creating new releases requires careful documentation, it also requires careful decision-making. At the end of the day, every decision that you make not only has an effect on your new release, but also on every previous release as well.