Stabilność API¶
Django zobowiązuje się zachowywać stabliność i kompatybilność wsteczną API. W skrócie, to znaczy, że kod, który pisałeś w jakiejś wersji Django będzie wciąż działał z przyszłymi wydaniami. Możesz musieć wprowadzić małe zmiany podczas upgrade’owania wersji Django, z której korzysta twój projekt: zobacz sekcje „Zmiany niekompatybilne wstecz” notatek o wydaniach dla wersji z której lub wersji z których się upgrade’ujesz.
At the same time as making API stability a very high priority, Django is also committed to continual improvement, along with aiming for „one way to do it” (eventually) in the APIs we provide. This means that when we discover clearly superior ways to do things, we will deprecate and eventually remove the old ways. Our aim is to provide a modern, dependable web framework of the highest quality that encourages best practices in all projects that use it. By using incremental improvements, we try to avoid both stagnation and large breaking upgrades.
Co oznacza „stabilny” (ang. stable)¶
W tym kontekście, stabilny oznacza:
Wszystkie publiczne API (wszystkie są w tej dokumentacji) nie będą przeniesione ani nie zostaną zmienione ich nazwy bez dodanych wstecznie kompatybilnych aliasów.
Jeśli do tych API zostaną dodane nowe elementy – co jest całkiem możliwe – nie złamią ani nie zmienią znaczenia istniejących metod. Innymi słowy „stabline” nie (koniecznie) zawsze znaczy „kompletne”.
Jeśli z jakiegoś powodu API określane jako stabilne musi zostać usunięte lub zmienione, zostanie oznaczone jako dezaprobowane, ale pozostanie w API w co najmniej dwóch kolejnych wydaniach. Przy wywołaniu dezaprobowanej metody wyświetlą się ostrzeżenia.
Zobacz Oficjalne wydania aby poznać więcej szczegółów o tym jak działa schemat numerowania wersji Django i kiedy funkcjonalności będą dezaprobowane.
Porzucimy kompatybilność wsteczną tego API bez procesu dezaprobowania tylko jeśli błąd lub dziura w bezpieczeństwie uczyni to absolutnie nieuniknionym.
Stabilne API¶
W ogólności, wszystko pokryte przez dokumentację – z wyjątkiem czegokolwiek w internals area jest uważane za stabilne.
Wyjątki¶
Tutaj znajduje się kilka wyjątków co do stabilności i wstecznej zgodności.
Poprawki bezpieczeństwa¶
Jeśli zauważymy problem bezpieczeństwa - w najlepszym przypadku za sprawą kogoś śledzą security reporting policy – zrobimy wszystko co konieczne by to naprawić. To może znaczyć brak wstecznej kompatybilności; bezpieczeństwo jest ważniejsze od gwarancji kompatybilności.
API oznaczone jako wewnętrzne¶
Niektóre API są wprost oznaczone jako „wewnętrzne” na kilka sposobów:
- Czasem dokumentacja odnosi się do elementów i oznacza je jako wewnętrzne. Jeśli dokumentacja mówi, że coś jest wewnętrzne, rezerwujemy prawo do zmiany tego
- Funkcje, metody i inne obiekty poprzedzone prefiksem podkreślenia (
_). Jest to standard Pythona mówiący, że coś jest prywatne; jeśli każda metoda zaczyna się pojedynczym podkreśleniem _, to jest to wewnętrzne API.
