Skip to content

Instantly share code, notes, and snippets.

@abmmhasan

abmmhasan/Release Note Guideline.md

Last active December 2, 2024 16:52
Show Gist options
  • Save abmmhasan/51b90f3678c63c51e7b081d609f92a3b to your computer and use it in GitHub Desktop.
Save abmmhasan/51b90f3678c63c51e7b081d609f92a3b to your computer and use it in GitHub Desktop.
Download ZIP
VCS Release Note Structure
Raw
Release Note Guideline.md

Release Note Guidelines

Guidelines for Effectiveness

  1. Understand Your Audience

    • Tailor the content based on your audience—whether they are technical users, general users, or decision-makers, use language they understand.
    • Avoid technical jargon and simplify complex terms for wider accessibility.

  2. Focus on Value for Users

    • Emphasize the benefits of updates rather than just listing features. Explain why each change matters to users.
    • Take a customer-centric approach, showing empathy for user needs and explaining how updates solve specific problems.

  3. Structure and Organization

    • Use clear headers and categories like "New Features," "Improvements," and "Bug Fixes" to make it easy for users to find relevant information.
    • Keep descriptions short and concise. Aim for tweet-length clarity.
    • Present changes in a logical sequence, placing the most impactful updates at the top.

  4. Visual and Interactive Elements

    • Incorporate screenshots, GIFs, or videos to illustrate major updates, making it easier for users to understand changes visually.
    • Use emojis, bullet points, and formatting to make release notes more visually appealing and easier to skim.

  5. Templates for Consistency

    • Maintain a consistent structure for release notes to ensure uniformity across different versions, helping users know what to expect.

  6. Highlight Important Changes

    • Provide a high-level summary at the beginning of the release note to quickly inform users of key updates.
    • Clearly state how changes impact user workflows and why they are important.

  7. Multi-Channel Communication

    • Publish release notes on multiple channels, such as a website, blog, email, or in-app messages, tailoring each to the platform’s audience.

  8. Brand Tone and Transparency

    • Use a brand-consistent tone, whether casual, professional, or humorous, to maintain engagement and connection with users.
    • Be transparent about known issues and expected timelines for fixes to foster user trust.

  9. Encourage User Feedback

    • Include a call to action for user feedback, such as a link to a survey or contact form. Engaging users helps inform future updates.

  10. Support Additional Learning

    • Offer links to user guides, tutorials, or support documentation for users wanting more information on new features.

  11. Date and Context

    • Always include the release date and provide context around changes to help users understand the significance of the updates.

  12. Provide a Roadmap

    • If possible, include a brief roadmap of upcoming features to inform users of what’s planned for future releases.

Technical Guidance for Release Notes Structure

  1. Commit-Based Content Creation: Release notes should be built from previous commit messages to ensure accuracy and completeness. If a Pull Request (PR) reference is available, follow the PR instead. If no PR is found, then follow the commits.
  2. Cap Category Points: Each category should be limited to a maximum of 10 points to keep the release note concise.
  3. Merge and Summarize: If there are multiple commits for the same feature (or improvement, bug fix, known issue), merge and summarize them to avoid overwhelming users with too many points for same feature. But can be kept as is if total commit hits less than 3. Overall, make sure honor the cap.
  4. Remove Empty Categories: If a category has no relevant content, it should be removed from the release note to maintain clarity.
  5. Semantic Versioning: Versioning should follow the Semantic Versioning strategy (Major.Minor.Patch).
    • Breaking Changes: Increment the MAJOR version (e.g., 1.0.0 → 2.0.0). These are changes that are incompatible with previous versions and may include modifications that affect APIs or functionality.
    • New Features: Increment the MINOR version (e.g., 1.0.0 → 1.1.0). These changes are backward-compatible enhancements that add functionality without breaking existing features.
    • Bug Fixes Only: Increment the PATCH version (e.g., 1.0.0 → 1.0.1). These are backward-compatible corrections for bugs without introducing new features or breaking changes.
    • Pre-release Versions: Use pre-release versions to indicate unstable releases that are not yet ready for production (e.g., 1.0.0-alpha, 1.0.0-beta).
    • Build Metadata: Append build metadata for additional version information that doesn't affect version ordering (e.g., 1.0.0+build123).
  6. Reference Commits: If commits are merged/summarized, postfix the related PR/Commit references in CSV format inside brackets for each point.
    • If there is PR reference, avoid Commit reference for same point
    • If no PR reference, use Commit reference in CSV formate

Structure

Release Notes for Version X.X.X

Versioning Format: X.Y.Z where X represents major changes, Y represents minor updates, and Z represents patch fixes. The versioning system follows the Semantic Versioning strategy.

Release Date: [Date]

Overview: A high-level summary of the most important changes to provide users with a quick understanding of what’s new and improved.

New Feature(s): (Up to 10 points, remove section if empty)

  • Feature Name 1: Briefly describe the new feature. Highlight its benefit to users. (Ref: [PR ID/Commit IDs])
  • Feature Name 2: Another brief description showcasing added functionality. (Ref: [PR ID/Commit IDs])

Improvement(s): (Up to 10 points, remove section if empty)

  • Improvement Description 1: Explain what has been enhanced, emphasizing user experience. (Ref: [PR ID/Commit IDs])
  • Improvement Description 2: State how existing functionality is better now. (Ref: [PR ID/Commit IDs])

Bug Fixe(s): (Up to 10 points, remove section if empty)

  • Issue Description 1: Outline the bug and its impact. Indicate the resolved state. (Ref: [PR ID/Commit IDs])
  • Issue Description 2: Mention how the issue was affecting users and confirm it’s fixed. (Ref: [PR ID/Commit IDs])

Known Issue(s): (Up to 10 points, remove section if empty)

  • Issue Description: Detail any known issues, if applicable, along with workarounds or planned resolutions. Include expected resolution dates or progress updates to help set expectations.

Note(s):

  • Please share feedback or report issues via [link to feedback channel or support]. For additional help, contact us at [contact method] during our support hours: [support hours].

Contributor(s):

  • Comma seperated contributor list (For open source projects, with linked contributors).

Example

Release Notes for Version 1.2.0

Release Date: November 20, 2024

Overview: This release brings exciting new features to enhance user productivity, alongside significant improvements for a smoother experience and bug fixes for more stable performance.

New Feature(s):

  • Custom Dashboard Layout: Users can now fully customize their dashboard layout, allowing for better personalization to match individual workflows and preferences. (Ref: [PR #1234])
  • Dark Mode: Added support for Dark Mode to reduce eye strain, especially in low-light environments. (Ref: [PR #1245])

Improvement(s):

  • Search Speed Enhancement: Optimized search algorithms, resulting in a 25% faster response time across all platforms. (Ref: [PR #1287])
  • Improved Notification Settings: Enhanced notification options now allow users to choose how and when to receive updates, providing greater flexibility. (Ref: [73b9df0, 67f8a9e])

Bug Fixe(s):

  • Login Issue on Mobile Devices: Resolved a bug that caused login failures on some mobile devices, ensuring a consistent experience across all platforms. (Ref: [PR #1300])
  • File Upload Crashes: Fixed an issue where uploading files larger than 100MB would crash the application. (Ref: [ e1a2b34])

Note(s):

  • Please share your feedback or report any issues via [support link]. For additional assistance, contact us at [support email] during our support hours: Monday-Friday, 9 AM to 6 PM (EST).

Contributor(s):

Hasan, Mahmud

Generation Guideline

  • Generate a release file (e.g. release.txt) using git log
  • Parse the file to extract PR & Commit details.
  • Extract required informations.
  • Bump the version according to the details.
  • Format the release notes.
  • Ensure clarity, consistency and adherence to guidelines.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment