Upgrade to Pro — share decks privately, control downloads, hide ads and more …

endoflife.date Recommendations

endoflife.date Recommendations

A talk about the importance of documentation, and what it takes to get it right. I cover learnings from the endoflife.date project, and recommendations I wrote down so other projects can follow them to better document their support lifecycles.

The talk covers best practices around documenting your release cadence, processes, EOL dates, versioning schemes, and various gotchas. There are lots of examples to showcase what is good vs bad (and why).

The talk comes out of my experience of creating endoflife.date as an open-source community project, and documenting the lifecycles and EOL dates of more than 100 products.

It is based on the recommendations listed at https://endoflife.date/recommendations. Presented at the FOSS United Meetup in Bangalore, June 2022.

Nemo

June 11, 2022
Tweet

More Decks by Nemo

Other Decks in Marketing & SEO

Transcript

  1. endoflife.date
    recommendations
    How to document support lifecycles effectively.

    View full-size slide

  2. angular laravel

    View full-size slide

  3. The Gold
    Standard

    View full-size slide

  4. kubernetes endoflife.date/k8s

    View full-size slide

  5. Understanding
    Expectations

    View full-size slide

  6. Updates
    Am I running a supported
    release? What does
    support mean?
    Support Compatibility
    What changes were made
    in release X. Will
    something break?
    Is there a new releases
    available? When is the
    next one due?
    Questions your release page is asked
    Lifecycle
    How long will release X
    get bug fixes or security
    fixes?
    Release Distinction
    Should I be running a LTS
    release? What’s the
    difference?
    Policy
    How are new releases
    versioned?

    View full-size slide

  7. Recommendations

    View full-size slide

  8. Be Helpful.
    Empathy

    View full-size slide

  9. Stick to one page, one website.
    In One Place

    View full-size slide

  10. Publishing
    wiki.ubuntu.com/ReleaseCadence
    ubuntu.com/about/release-cycle
    wiki.ubuntu.com/Releases
    example.com/docs/v3.4/eol (?)
    devguide.python.org
    GOOD
    example.com/docs/eol
    example.com/release-policy
    angular.io/guide/releases
    php.net/supported-versions.php
    BAD

    View full-size slide

  11. Tell what’s supported and for how long
    Document
    the lifecycle

    View full-size slide

  12. How often are you making new releases?
    Release
    Cadence

    View full-size slide

  13. Release Cadence
    Saying nothing.
    GOOD
    - Ubuntu
    - Every month
    - Every Christmas (Ruby)
    - Every 29th February
    - Maybe once every 2 weeks, but not
    guaranteed.
    - Whenever needed.
    - No release cadence.
    BAD

    View full-size slide

  14. What does
    Support
    mean?

    View full-size slide

  15. ● Priority security fixes.
    ● Critical bugfixes.
    ● Issues will be looked at
    ● Community Forum for
    support.
    Different Meanings
    ● Only packages in the
    “main” repository.
    ● Only if you are a paying
    customer.
    ● Free for 3 machines.
    ● Only packages covered
    by our upstream LTS.
    ● As long as you’re
    running a support
    Python version.
    Conditions Applied*

    View full-size slide

  16. Provide a list of “supported releases”.
    What is
    supported?

    View full-size slide

  17. elasticsearch

    View full-size slide

  18. Be accurate, and exact.
    Dates

    View full-size slide

  19. “2022 December” might mean
    upgrading on new year or not.
    Absolute Dates
    Don’t make your users do the
    math every time.
    No Ambigous Dates
    07-07-2021 is bad.
    RFC3339 FTW!
    Complete Dates
    How to document dates correctly

    View full-size slide

  20. Calendar Images

    View full-size slide

  21. - Clearly labelled X-axis (Years, Quarters)
    - Well sorted releases.
    - Mark the current date
    - (Interactive) Show information on hover.
    - Keep it updated!
    - Accessible
    Good Release Calendar Images

    View full-size slide

  22. What all to document
    Essential
    Information

    View full-size slide

  23. Changelog Dates
    Download/Upgrade
    Links
    Migration Guide
    Unsupported
    Releases
    What all to list for every release cycle
    How do I get this release?
    Helpful for complicated
    upgrades.
    Don’t list these alongside
    supported ones.
    A link to the changelog for
    the latest release, not just
    the first one.
    Latest
    What’s the latest release
    in this cycle (and is it
    supported)?
    Release, Latest Release
    Date, LTS Date, Support,
    EOL

    View full-size slide

  24. Node.js
    ● Changelog
    ● Latest Release
    ● Dates
    ● Download
    ● Migration
    ● Unsupported
    Releases
    ● Today’s Date
    BONUS
    ● Future releases
    ● Calendar

    View full-size slide

  25. kubernetes
    ● Changelog
    ● Latest Release
    ● Dates
    ● Download
    ● Migration
    ● Unsupported
    Releases

    View full-size slide

  26. Python
    ● Changelog
    ● Latest Release
    ● Dates
    ● Download
    ● Migration
    ● Unsupported
    Releases

    View full-size slide

  27. Azure Kubernetes Service
    ● Changelog
    ● Latest Release
    ● Dates
    ● Release Notes
    ● Unsupported
    Releases

    View full-size slide

  28. Amazon EKS
    ● Changelog
    ● Latest Release
    ● Dates
    ● Release Notes
    ● Unsupported
    Releases

    View full-size slide

  29. haproxy
    ● Changelog
    ● Latest Release
    ● Dates
    ● Download
    ● Migration
    ● Unsupported
    Releases

    View full-size slide

  30. 🔗endoflife.date/recommendations
    Be Helpful
    Credits & Slides: captnemo.in/talks

    View full-size slide