Controleren of een verouderde API in een technisch artikel nog werkt

Noteer de bibliotheek, het volledige importpad of de volledige methodenaam en de versie waarvoor het artikel bedoeld is. Alleen een naam kan dubbelzinnig zijn: pakketten kunnen API’s met vergelijkbare namen aanbieden, en een artikel kan naar een oude versie verwijzen terwijl de huidige documentatie een nieuwere versie beschrijft. Controleer de imports in het codevoorbeeld en de context eromheen om het daadwerkelijke symbool vast te stellen.

Zoek vervolgens de officiële documentatie voor de versie die in het artikel wordt genoemd. Let op statuslabels zoals ‘verouderd’, ‘verwijderd’ of ‘niet achterwaarts compatibel’. Vergelijk die daarna met de documentatie voor de versie die een lezer zou gebruiken. Een actuele documentatiepagina kan een oude API volledig weglaten. Dat is een aanwijzing om verder onderzoek te doen, maar geen bewijs van wanneer of waarom de API is verdwenen.

Release notes koppelen een wijziging aan een specifieke release. In de release notes van Django 3.1 noemen de beheerders django.conf.urls.url() als verouderd en wijzen ze django.urls.re_path() aan als alternatief. In de release notes van Django 4.0 staat dezelfde API bij de functies die na afloop van hun verouderingscyclus zijn verwijderd. Deze twee vermeldingen leggen de volgorde vast: verouderd in 3.1, verwijderd in 4.0.

Leid geen releasedatum of verwijderingsdeadline af uit een verouderingsmelding, tenzij het project die vermeldt. Projecten verschillen in hoe lang ze verouderde interfaces behouden, en sommige bieden lange tijd compatibiliteit. Wanneer een release note vermeldt dat een API is verwijderd, controleer dan of dit voor de volledige API geldt of dat er uitzonderingen worden genoemd. Django 4.0 vermeldt bijvoorbeeld dat NullBooleanField is verwijderd, behalve voor ondersteuning in historische migraties. Die uitzondering is van belang voor beheerders die met oude migratiebestanden werken.

Een vervanging kan er vergelijkbaar uitzien, maar ander gedrag of andere vereisten hebben. Volg de migratiepagina waarnaar de release notes verwijzen en bekijk daarna de versiegebonden referentie van de vervanging. In de versie-upgradehandleiding van Django wordt aangeraden verouderingswaarschuwingen in de huidige versie op te lossen voordat je doorgaat met een upgrade. Zo wordt een vage documentatiecontrole een praktische reeks stappen: voer de upgrade uit binnen de ondersteunde stappen, breng waarschuwingen aan het licht, werk het eigen gebruik in het project bij en stap pas daarna over naar een versie waarin de API is verwijderd.

Voor het Django-URL-voorbeeld is re_path() de gedocumenteerde vervanging. Controleer het importpad en het gedrag aan de hand van de documentatie voor de doelversie. Deze historische releases illustreren de wijziging; dit is geen aanbeveling om ze vandaag te installeren.

Gebruik precieze statusomschrijvingen:

Leid de huidige onderhoudsondersteuning niet af uit het feit dat een voorbeeld in één omgeving werkt. Controleer of de exacte doelversie de API als beschikbaar documenteert en zoek in latere versies naar verouderingsmeldingen. Dat een API in een oude release beschikbaar is, betekent niet dat die release nog wordt onderhouden.

De standaardbibliotheek van Python laat zien waarom versienummers ertoe doen. In de notities ‘Wat is er nieuw’ van Python 3.9 staat dat aliassen zoals collections.Mapping sinds Python 3.3 een DeprecationWarning gaven en dat Python 3.9 de laatste versie was waarin die aliassen voor achterwaartse compatibiliteit beschikbaar waren. Dezelfde notities raden aan om met waarschuwingsopties te testen, zodat verouderde API’s aan het licht komen. Een artikel dat collections.Mapping zonder Python-versie simpelweg ‘verouderd’ noemt, laat lezers niet weten of ze een waarschuwing krijgen of dat het attribuut ontbreekt. Geef de voorkeur aan de gedocumenteerde locatie collections.abc en controleer de status in de release notes van de beoogde Python-release.

Kies na het controleren van de keten één actie voor het artikel. Als het voorbeeld volgens de documentatie beschikbaar is in de vermelde omgeving, geef dan de versie en status nauwkeurig aan. Als de API verouderd maar nog beschikbaar is, vermeld dat duidelijk, toon de vervanging en leg uit op welke versie lezers zich moeten voorbereiden. Als de API is verwijderd, werk dan de code bij en vermeld de eerste release waarin deze niet meer beschikbaar is. Behoud alleen een historische toelichting als lezers die nodig hebben om oude projecten te begrijpen.

Een beknopte notitie met bewijs helpt toekomstige onduidelijkheid te voorkomen: noteer de exacte naam van de API, de eerste release waarin deze verouderd werd verklaard, de verwijderingsrelease indien van toepassing, de vervanging en de URL’s van de officiële bronnen. Als de officiële bronnen geen verwijderingsversie of vervanging vermelden, zeg dan dat de status onduidelijk is in plaats van de leemte op te vullen met een gekopieerd codefragment of een niet-geverifieerd artikel. Zo ontstaat een correctie die specifiek is voor een versie en waar lezers mee aan de slag kunnen, in plaats van een tijdloze bewering dat een API ‘oud’ is.