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.

929e39cbad5d2599dfe72fe89e06de2a?s=128

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.

  2. whoami

  3. None
  4. angular laravel

  5. The Gold Standard

  6. php

  7. kubernetes endoflife.date/k8s

  8. Understanding Expectations

  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?
  10. Recommendations

  11. Be Helpful. Empathy

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

  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
  14. Tell what’s supported and for how long Document the lifecycle

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

  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
  17. What does Support mean?

  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*
  19. Provide a list of “supported releases”. What is supported?

  20. elasticsearch

  21. Be accurate, and exact. Dates

  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
  23. Calendar Images

  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
  25. None
  26. ubuntu

  27. What all to document Essential Information

  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
  29. Showcase

  30. Node.js • Changelog • Latest Release • Dates • Download

    • Migration • Unsupported Releases • Today’s Date BONUS • Future releases • Calendar
  31. kubernetes • Changelog • Latest Release • Dates • Download

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

    • Migration • Unsupported Releases
  33. Azure Kubernetes Service • Changelog • Latest Release • Dates

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

    Release Notes • Unsupported Releases
  35. haproxy • Changelog • Latest Release • Dates • Download

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