DevRel Scribbles
  • What are Scribbles?
  • Index
  • Developer Advocacy
  • Developer Advocates
  • Life as a developer advocate
  • Modernising Red Hat’s enterprise developer program
  • Engaging 9-year-old software developers
  • Making 22-year-olds love 26-year-old software
  • Dogfooding developer products: gathering insights from internal hackathons
  • How far does your ethical responsibility stretch for the tech your devs create?
  • Outside the lecture theatre
  • How do you design programs for diversity?
  • Build the Platform Your Developers Actually Want
  • Measuring dev rel programs far beyond marketing activities
  • Developer Evangelism
    • Developer Evangelists
    • How to rock a technical keynote
    • The Art of Slide Design
    • The Art of Talk Design
    • The Art of Story Design
    • Dev events beyond 2021
  • Developer Experience
    • The Power of Content
    • Building a Developer Community in an Enterprise World
    • How to lose a dev in three ways
    • Developer relations, why is it needed?
    • The hierarchy of developer needs
    • GitHub is your documentation landing page
    • Docs as engineering
    • Commit messages vs. release notes
    • A11y pal(ly)- crafting universally good docs
    • Inspiring and empowering users to become great writers, and why that’s important
    • Solving internal technical documentation at Spotify
  • Community Management
    • Building community flywheels
    • DevRel = Community Management?
    • Creating high-quality communities
    • How to grow a healthy Open-Source community?
    • Managing communities at scale
    • Using community to drive growth
    • Useful community success metrics
    • Communities aren't funnels
    • How to mobilise your community during a pandemic
  • Managing a DevRel Team
    • Developer Relations + Product
    • Distributed developer relations
    • Understanding company goals
    • DevRel Qualified Leads (DQL)
    • Path to success for DevRel
    • How to move up in your organization
    • Four pillars of DevRel
    • Building your DevRel dream team
    • Managing the burnout burn-down
    • I messed up and I’m going to get fired
    • How to report on community relationships without being creepy about it
    • How to scale a developer relations team
  • Misc
    • Is developer relations right for you?
    • Tooling your way to a great DevRel Team
    • Planning your DevRel career
    • Success metrics as narratives
    • Get executive buy-in or else
    • Introduction to the AAARRRP devrel strategy framework
    • Strategy for developer outreach
    • Connecting dev rel and product
    • Performance DevRel
    • Ultimate cheat codes for healthier travel
Powered by GitBook
On this page
  • Summary:
  • Scribbles:
  • Commit messages
  • Release notes
  • ‌Audience
  • Comparison

Was this helpful?

Export as PDF
  1. Developer Experience

Commit messages vs. release notes

Can you make good release notes by collating your commit messages? Eva Parish argues not. Eva Parish explains the different purposes of commit messages and release notes.

PreviousDocs as engineeringNextA11y pal(ly)- crafting universally good docs

Last updated 3 years ago

Was this helpful?

Summary:

  • Why don’t we just scrape a list of all the commits that went into the last release, and boom, instant release notes?”

  • Having well written and consistent commit messages are important and having great release notes is also important, the two are not interchangeable.

  • Commit messages are terse technical descriptions of what you’ve changed in a unit of work and why, for an audience of developers.

    • Commit messages are a chance to capture the context around what you’ve done in a way that will make things easier for your future self and your coworkers.

    • It only takes a few extra seconds of brainpower to write a commit message that’s useful

  • Release notes are a list of the important user-facing changes in a release, generally written at a less technical level of detail and focusing more on behaviour.

    • Release notes are an excellent opportunity to tell your users about the awesome thing you’ve built and why they should use it.

Scribbles:

Commit messages

  • Commit messages to record brief technical details of what you’ve changed in a unit of work.

  • Be brief but still complete enough that someone can get a sense of what happened.

  • Why are you making this change?

  • It’s less important to focus on the details of how you accomplish something‌.

Audience

  • You can assume that your reader is pretty technical but they don’t have all the context.

  • This is why it’s important to include the reasoning.

On my team, we like to say that good documentation is like a love letter to your future self.

Release notes

  • A high-level and less technical summary of what’s changed about a product or a feature or an API in a release.

  • Your release notes should be written at a less technical level than your commit messages.

  • Focus on the resulting behaviour and not how you did it.

  • Release notes should be framed from the perspective of the end-user.

‌Audience

  • Your users and there’s a wide range, depending on what your product is.

  • Your users might be super non-technical or they might be developers just like you.

  • Think about what information they need to know.

    • Did you make some kind of improvement?

    • Did you change how something existing works?

    • Will they need to refactor code to remove an API you deprecated?

    • What will look or feel different to them when they’re using the product?

‌

Comparison

Commit Messages

  • There’s a ticket number, it starts with a verb in the imperative.

  • It briefly mentions all the pertinent details,

    • The library name

    • The version number

    • Efficiently states “why”, which is -- support for gifs.

Release note

  • You have a bit more room for information in a release note.

  • Starts by talking about what the change enables the user to do.

  • Links out to further reading, where they can get help if needed.

  • And it ends with inspiration for what the user can do to get started using this new thing. ‌

How do you get started writing great release notes?

  • Don't recycle wholesale.

  • You can look back through your Git history to remind yourself of what you’ve done,

    • Pick out the changes that are most interesting or impactful to a user.

  • And feel free to leave things out because there are plenty of things in your Git history that a user doesn’t care about.

  • Take each one and imagine it from your user’s perspective.

    • How will this affect them?

    • What differences will they notice in the product?

    • Are there any breaking changes or actions that they have to take?

  • Adjust the level of technical detail as appropriate, based on what you know about your users.

“Good release notes get users excited about the hard work that you’ve put in to building your product. So use both commit messages and release notes appropriately and don’t waste these opportunities.”

Example of a new version of the emoji library to make emojis out of gifs.
Video