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.

Transcript

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

   View Slide

2. whoami
   

   View Slide

3. View Slide

4. angular laravel
   

   View Slide

5. The Gold
   Standard
   

   View Slide

6. php
   

   View Slide

7. kubernetes endoflife.date/k8s
   

   View Slide

8. Understanding
   Expectations
   

   View Slide

9. 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 Slide

10. Recommendations
    

    View Slide

11. Be Helpful.
    Empathy
    

    View Slide

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

    View Slide

13. 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 Slide

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

    View Slide

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

    View Slide

16. 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 Slide

17. What does
    Support
    mean?
    

    View Slide

18. ● 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 Slide

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

    View Slide

20. elasticsearch
    

    View Slide

21. Be accurate, and exact.
    Dates
    

    View Slide

22. “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 Slide

23. Calendar Images
    

    View Slide

24. - 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 Slide

25. View Slide

26. ubuntu
    

    View Slide

27. What all to document
    Essential
    Information
    

    View Slide

28. 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 Slide

29. Showcase
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide