1. + • New Release Check Procedure Sample
2. + • New Release Check Procedure Form
3. • New Release Check Procedure Template
4. • New Release Check Procedure Requirements

One step in the development process for all software is the release. Some projects continually release, while others demarcate certain states of the codebase in a more formal, numbered way. Scientists leading the development of research software may be interested in how I manage my own software releases and encapsulate some reproducibility best practices along the way. A quick Google search turns up a plethora of 'software release checklists.' This blog post summarizes mine.

One of my projects, PyRK, a python tool for reactor kinetics, recently had a release. To be as transparent, robust, and citable as possible, the PyRK project employs a release procedure that relies on version control (Git), a ticketing system (GitHub), automated documentation (Sphinx), a website (Read the Docs), a test framework (nose), continuous integration (Travis CI), and an archival system that generates digital object identifiers (DOIs) (figshare). At the heart of all of this is a software-development process inspired by GitFlow, which incorporates testing and code review. I won’t cover that workflow in this blog post; I’ll instead focus on the process in the image, a typical scientific software-release procedure. While the particular software stack I use in this example is tailored to python projects, the concepts are common across programming languages.

Maintaining clear documentation and a transparent development process, especially in the context of a release, allows other scientists to discover and use our scientific software. PyRK is a python project, so we use Sphinx and its api-doc utility to automatically document the classes and functions that make up the source code. This requires that we add well-formatted docstrings to our classes and functions. Sphinx does the rest. That generated documentation is then hosted within a website built with Read the Docs. To help us in the development process, we collect all proposed changes to the codebase in “issues” and tag those issues into “milestones” using GitHub. When all “issues” in the “release v0.2” milestone are complete, we’re then ready to release the new version of the code. The closed issues in the milestone captures the changes represented by the release, so users can review the changes represented by the release.

Much of the work of code robustness happens during the development process but aids in the release process. That is, during development, we constantly add unit tests to ensure that code changes achieve the behaviors we expect. Those unit tests are run in the nose testing framework and tested across supported platforms using Travis CI. As part of the release procedure, it is important to double check that the test coverage is sufficient and tests are passing.

New page in Wiki named 'Releasex.y.z' for release procedure with steps needed and their status (based on Release Template), at the beginning consisting of (at least) RC1 and final release sections. If it is a final release add a link it to Releasing. The University will represent its supervisors in a court action resulting from any good faith, non-malicious response to a reference check. Title VII of the Civil Rights Act of 1964 provides protection from discrimination on the basis of race, color, religion, national origin, or sex.

Scientific software often contains scientific models and algorithms, the use of which should be cited by users when they contribute to scientific work. Citing code has historically been tricky, but some services now allow code to receive a DOI, which is archived and can be cited like a journal article is cited. figshare allows me to create a citeable DOI from the release tag on GitHub. I also include this information in a citation file in the software repository and on the software website.

My checklist, summarized in the image, goes like this:

• Address open issues associated with the release milestone (use a ticketing system like GitHub's)
• Confirm the closed issues in the milestone capture the changes represented by the release
• Confirm all tests pass (with a test framework like nose)
• Confirm builds and tests pass on all supported platforms (use continuous integration like travis)
• Update documentation (automated with a tool like Sphinx)
• Update other website information, like new authors, release notes, etc. (Read the Docs)
• Tag the revision of the code with a release tag (Git/GitHub).
• Upload it to an archive that generates DOIs (figshare)
• Update the citation file to include the release citation from figshare (CITATION.md)
• Celebrate.

A subtle issue not covered in the above list is that of “release candidates.” In projects with more than a few users, each release turns up a small flurry of bugs encountered by the “tire kicking” of its users. To quickly fix those bugs and include them in the release, many teams put out a test release, wait for the bug reports, fix those bugs, and then proceed with the real release. The process for iteration on releases and release candidates isn’t as necessary for small projects, but is something to be aware of as your project grows.

So, in conclusion:

• For transparency, we use a version-control tool, a ticketing system, an automated documentation tool, and a website.
• For robustness, we employ unit tests, continuous integration, and code review in a controlled way.
• For citability: we have a citation file and use a service like figshare to acquire a DOI.

It’s finally here! After months of hard work and patience, your software masterpiece of a product release is ready now. You are more than eager to set the wheels in motion, but wait, are you safely locked and loaded? No one ever got a second chance to make the first impression. So, it’s about time you take the right steps towards a successful product release. What salient points does one need to check on to ensure a successful product release anyway? Read on as we spill the beans.

# 1 Assemble Your Resources

For any kind of rollout to phase out successfully, it’s important to ensure all resources needed to make the deployment possible are easily accessible. These resources may be materials, tools and even personnel needed to perform designated activities listed for a particular rollout.

Being obstacle – ready will help you go a long way. There may be instances when the resources become unavailable. A staff member may be on leave or is tending to another project or the desired tools may be unavailable. In such cases, you must be prepared with an alternative solution and continue with the release process. However, it is important to get an approval from the change management team before the rollout. The best way to mitigate issues cropping up due to resource crunch is to plan ahead of time. It is best to include staff vacations and holidays in the deployment schedule and consider adding a time buffer to avoid surprises due to sudden resource unavailability.

# 2 Clearly Communicate All Release Details

Your communication with stakeholders should have to do more than just generating awareness about the release or telling everyone how important it is for the business. Shift your focus to developing organizational readiness. Ensure to communicate release-related information like release dates and plan, places where they can find any training courses (if required) and references where the support staff, users, and others involved in the release process can read more about the release. You may also want to do a Q & A session to answer any queries. Releasing a detailed FAQ doc is also a good alternative. Also, provide users with a list of actions they may need to carry out to prepare their workstations before and after the release. A product change log, emails, blog posts, videos or customer tutorials are some good ways of doing this.

#3 Establish a Regular Release Cycle

A release cycle is the heartbeat of the product release process. Thus, it becomes essential to determine how often should the code be pushed into production. For instance, GitHub deploys code multiple times in a day, as soon as it is ready, and so does Quora. This helps in establishing a timetable for when certain functionality will be available for the stakeholders. Besides, it creates a set routine where all the teams (engineering, marketing etc.) can align. However, it is important to have an accurate release cycle, and not some random number you can work with at the dinner table. Before you announce it, test it. An inaccurate release cycle is the most common cause of a failed release process.

Example of a Release Cycle

#4 Plan and Implement an Early Release Infrastructure

Developing a software isn’t enough. It is also crucial to ensure that users can access it easily. That’s where a release infrastructure comes into play. Release infrastructure is an often temporary setup put in place to deploy a software and facilitate its use. Ideally, a release infrastructure comprises of hardware, storage, bandwidth, network connections, user profiles, licensing, access permissions, skills and human services. Planning out the release infrastructure at the initial stages helps in identifying any hidden bottlenecks like missing hardware or absent skills. Resolving them early will ensure that there isn’t any delay in software release.

+ • New Release Check Procedure Sample

Plan and Implement an Early Release Infrastructure

# 5 Version Your Releases

Releasing product without versioning can make it difficult to track issues and deal with user expectations. Everyone knows that releasing a product’s beta version means it is somewhere between the two phases of being ‘functional and hideous’ to ‘polished and ready to go’. So, users approach the product with that amount of caution. Not marking your product as a beta version, is akin to losing that ‘starter-sympathy’ from enthusiastic users.

Further, if you release a fixed release and don’t version it either, it won’t be clear which release is affected. Using a standardized major and minor release version numbers helps manage expectations about the scale of change. Going from 3.0 to 4.0 means there is a substantial change in the software, while upgrading from 3.1 to 3.2 depicts small changes and enhancements.

+ • New Release Check Procedure Form

# 6 Test Your Release Yourself

In a rush to release the product in time, you might miss a step, and the release may stop working. This can be easily avoided. Just download the new release and skim through the process of building, installing and testing it. This will help in ensuring that the download links are working and the software is ready to use.

# 7 Don’t Get Caught Up with Making the Product Perfect

• New Release Check Procedure Template

While it is important to ready your software for release, it isn’t necessary to make it perfect. To be honest, a perfect software is a myth. There will always be some scope for tweaking or adding and updating features. The key here is expectation management. Have it all figured out – what the software can and cannot do and what more needs to be done from your end. Over time, you may realize how some features you were initially fretting over may not be so relevant afterall. Here’s Nick Barnes in an editorial for Nature magazine, speaking on when it’s okay to release your code.

• New Release Check Procedure Requirements

What are your routine checkups before approaching a product release? Let us know in the comments below.