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.
2. whoami
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
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