Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add Release Checklist article to "Approach" section #731

Closed
wants to merge 9 commits into from
Closed

Add Release Checklist article to "Approach" section #731

Changes from 8 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
0c356db
Initial commit
kewlguy781 Sep 27, 2024
bc072d4
Update content/engineering/our-approach/release-checklist.md
kewlguy781 Sep 27, 2024
91b0674
Update content/engineering/our-approach/release-checklist.md
kewlguy781 Sep 27, 2024
d3abc6a
fixed links
kewlguy781 Sep 27, 2024
cf4ce19
minor edit
kewlguy781 Sep 27, 2024
c4befe1
Changing spaces as per comment from Michael (thanks!)
kewlguy781 Oct 3, 2024
ab038dc
removed slack channel
kewlguy781 Oct 3, 2024
379fb3b
added ATO link
kewlguy781 Oct 7, 2024
433aec3
added example
kewlguy781 Oct 11, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 94 additions & 0 deletions content/engineering/our-approach/release-checklist.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
---
title: Release checklist
sidenav: true
sticky_sidenav: true
tags: engineering
permalink: /engineering/our-approach/release-checklist/
redirect_from:
- engineering/release-checklist/
layout: layouts/page
eleventyNavigation:
parent: engineering_approach
key: Release checklist
order: 10
title: Release checklist
subnav:
- text: What is a release checklist?
href: "#what-is-a-release-checklist"
- text: Why does having a release checklist matter?
href: "#why-does-having-a-release-checklist-matter"
- text: What should be included in the checklist?
href: "#what-should-be-included-in-the-checklist"
- text: Resources
href: "#resources"
---
## What is a release checklist?

A release checklist is not just a procedural document; it is a critical component of ensuring that software releases are smooth, reliable, and meet the necessary quality standards and requirements. It helps in mitigating risks, improving collaboration, and ensuring consistency throughout the software development lifecycle.

## Why does having a release checklist matter?

A release checklist is crucial in software development for several reasons:

1. **Ensuring Quality Assurance**: The checklist helps ensure that all aspects of the software have been thoroughly tested and meet the required quality standards before release. It includes checks for functionality, performance, security, and usability among others.

2. **Consistency and Compliance**: It ensures that the release process follows a consistent set of steps and adheres to organizational policies and compliance requirements. This helps in maintaining reliability and reduces the risk of overlooking critical steps.

3. **Risk Mitigation**: By systematically checking off items on the checklist, teams can identify potential risks or issues early in the release process. This proactive approach allows for timely resolution of problems, reducing the likelihood of costly errors in production.

4. **Communication and Collaboration**: The checklist serves as a communication tool between different teams involved in the release process (development, testing, operations, etc.). It helps in aligning everyone on what needs to be done and ensures that all stakeholders are on the same page.

5. **Documentation**: It serves as a record of what has been tested and verified before the release. This documentation is valuable for audit purposes, troubleshooting post-release issues, and for future reference.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These two (Communication/collaboration and Documentation) feel like the pieces that make a release checklist valuable in conjunction with more developer-focused tools like good integration/unit tests and CI/CD pipelines. A checklist like this helps keep a team on the same page with regards to what's been done and what still needs to be addressed. I think there's an opportunity to use this page's introductory paragraph to frame the importance of the communication/documentation part of this.

6. **Improving Release Process**: Over time, the checklist can be refined and improved based on past experiences and lessons learned from previous releases. It becomes a valuable tool for continuous improvement in the software development lifecycle.

7. **Confidence and Transparency**: A well-executed checklist instills confidence in stakeholders (both internal and external) about the reliability and stability of the released software. It demonstrates transparency in the release process, showing that due diligence has been applied.



## What should be included in the checklist?

A release checklist in software development is a structured list of tasks and checks that need to be completed before a software release is considered ready for deployment to production or to end-users. It serves as a systematic guide to ensure that all necessary steps have been taken and all quality criteria have been met before releasing the software.

Here are some key components typically included in a release checklist:

1. **Functional Testing**: Verify that all new features, enhancements, or bug fixes work as expected according to the defined requirements and specifications. This also includes user experience/user acceptance testing.

2. **Integration Testing**: Ensure that the software integrates correctly with other systems or components it interacts with, such as databases, APIs, or third-party services.

3. **Performance Testing**: Check the software's performance metrics (e.g., response times, throughput) to ensure it meets performance requirements under expected load conditions.

4. **Security Testing**: Validate that security measures (e.g., authentication, authorization, data encryption) are in place and functioning correctly to protect against vulnerabilities.

5. **Deployment Readiness**: Ensure that deployment packages are prepared, deployment scripts are tested, and necessary configurations (e.g., environment variables, server settings) are set correctly for the production environment.
Comment on lines +53 to +63
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@kewlguy781 -- we talked about this in our 1:1 -- what are your thoughts on how these items on a release checklist fit into a project that's using CI/CD and DevOps?

Taking the security testing item as an example. I'd expect any 18F software project near release to be running automated security scans on a regular basis (e.g. on every PR) and running automated tests on every commit.

Are there specific security-related testing steps that come to mind as important to call out in a release checklist -- above and beyond the security testing that happens on every commit or every PR under continuous integration?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Launch guide does cover that. I am not sure if we want to repeat these that are already mentioned in the launch guide. Thought?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Which section(s) of the launch guide?

To my understanding, the launch guide is TTS-only whereas this resource will be public. So I think the Release Checklist article will need to stand on its own -- we shouldn't assume anyone reading Release Checklist will also be able to read the Launch guide.


6. **Documentation**: Confirm that user manuals, release notes, and any other relevant documentation are updated and accurate.

7. **Backup and Rollback Plans**: Verify that backup procedures are in place and tested, and that rollback procedures are documented and ready to be executed if needed.

8. **Compliance Checks**: Ensure that the release complies with legal, regulatory, and organizational policies (e.g., licensing, data protection). Your system may need a new ATO (Authority to Operate) or to be covered under an existing ATO. [Learn more about the ATO](https://digital.gov/resources/an-introduction-to-ato/).

9. **Communication Plan**: Plan for communicating the release to stakeholders, end-users, and support teams, including notifications, release announcements, and support availability. Does your agency have a process to approve communications outside of your agency?

10. **Post-release Monitoring**: Establish monitoring and logging to track the software's performance and user feedback after release, enabling quick detection and resolution of any issues that arise.


The following “columns” are strongly recommended in order to make information accurate and clear to track:

kewlguy781 marked this conversation as resolved.
Show resolved Hide resolved
**Owner**: Who owns this item in the checklist?

**Date and Time**: What is expected for this to be completed? How long will it take to complete this?

**Explanation of Task**: What is expected of the task being completed in this?

**Status**: What is the status of this? It can be set to the following fields: Pending, Started/In Progress, Completed/Done, Blocked

**Notes**: Any notes that would like to be reviewed at a later time. This can be used for reflection meetings and to improve the checklist after the release for the next release.


The release checklist is typically tailored to the specific needs and processes of the agency, the department, or project. It is often managed and maintained by a project manager, release manager or a release team to ensure consistency and thoroughness across releases. By following a release checklist, teams can reduce the risk of releasing faulty or incomplete software, improve communication and collaboration among team members, and enhance overall confidence in the software release process.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is often managed and maintained by a project manager, release manager or a release team to ensure consistency and thoroughness across releases.

I think this should go in the intro. Perhaps we need a couple of sentences about how the team uses the checklist?

### Resources:
[18F Launch Preparation](https://docs.google.com/document/d/1gJcvQ-o0DMEUY3m19KGPw8y6qFPvdX7FWC6OSlURRmM/edit)

[Examples of other project release checklists](https://drive.google.com/drive/folders/1zpBpZ9OjfHDuCJIrF8Uqzuu7VsdZ1s8-)
Comment on lines +99 to +102
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@kewlguy781 Suggestion -- link directly to an example checklist that models the structure you lay out in this article.

The Examples link goes to a folder that contains a variety of documents and checklists -- as a reader it's hard to know which I should look at first and which one best models the structure you lay out here.

Loading