Kontrola Wersji
Utrzymywanie kilku wersji API umożliwia ulepszanie usługi bez szkody dla kompatybilności wstecznej. Z jednej strony pojawiają się ciągle nowe wymagania, które wymagają zmian, z drugiej strony każda zmiana w interfejsie programu może wpłynąć negatywnie na działanie istniejących wtyczek. Aby rozwiązać ten problem, API posiada kilka wersji: w pewnym momencie wersja przestaje być rozwijana, interfejs zostaje zamrożony, a rozwój kontynuuje się w kolejnej wersji. Niezależnie od wprowadzonych później zmian, wtyczka opracowana dla zamrożonej wersji będzie działać poprawnie, dopóki ta wersja jest wspierana.
Cykl życia wersji
Większość wersji LTS (Long-Term Support) jest wydawana mniej więcej co dwa lata i wspierana przez około cztery lata. Pośrednie wersje podglądowe są wydawane pomiędzy takimi wersjami co trzy miesiące i wspierane przez pół roku. W ten sposób w każdym momencie wspieramy dwie najnowsze wersje LTS, dwie najnowsze wersje podglądowe (lub jedną, jeśli wersja LTS została wydana w poprzednim kwartale), a wersja LTS będąca w trakcie rozwoju jest dostępna do wglądu.
Wersje LTS to kolejne liczby całkowite — V1, V2, V3, V4, V5, V6 i tak dalej. Wersje podglądowe to pośrednie wersje LTS w trakcie rozwoju, dlatego mają numer wersji LTS z prefiksem Preview, na przykład V8Preview1, V7Preview2 i tak dalej aż do V8Preview7, po czym zostanie wydana wersja LTS V8.
Harmonogram wydań
Po wydaniu nowej wersji LTS role są przypisywane w następujący sposób:
- przestarzała wersja nie jest już wspierana;
- stabilna wersja staje się przestarzała;
- wersja w fazie rozwoju zostaje zamrożona i staje się stabilna;
- pojawia się nowa wersja w fazie rozwoju.
Cykl wersji podglądowych jest nieco prostszy.
- przestarzała wersja podglądowa nie jest wspierana;
- aktualna wersja podglądowa zostaje ogłoszona przestarzałą;
- kopia aktualnego stanu wersji LTS będącej w fazie rozwoju jest wydawana jako nowa aktualna wersja podglądowa.
Wybór wersji
Domyślnie zaleca się korzystanie ze stabilnej wersji LTS; pozwala to zminimalizować wysiłki migracyjne przy wydawaniu nowych wersji API. Jeśli wymagane są nowe funkcje, które nie są jeszcze dostępne w wersjach LTS, zaleca się korzystanie z aktualnej wersji podglądowej; w takim przypadku migracja między wersjami podglądowymi jest wymagana co 3-6 miesięcy, aż do wydania nowej wersji LTS. Nie ma sensu rozpoczynać procesu rozwoju dla przestarzałych wersji, ponieważ takie wersje są wspierane tylko dla celów kompatybilności wstecznej w okresie, gdy nowa wersja API jest już dostępna, ale wtyczki jeszcze nie zostały do niej przełączone. Nie zaleca się korzystania z wersji w fazie rozwoju, ponieważ jej interfejs nie jest jeszcze zamrożony, kompatybilność wsteczna nie jest zapewniona, a wersja ta podlega zmianom. Ta wersja jest udostępniana, aby można było poznać nowe funkcje i rozwijać wtyczkę z wyprzedzeniem dla nadchodzącej wersji API, tak aby w momencie jej wydania wtyczka była gotowa (lub prawie gotowa) do udostępnienia nowych funkcji.
Wersję API, dla której rozwijana jest wtyczka, można określić przez wersję interfejsu IFrontPlugin. Na przykład, jeśli wtyczka odnosi się do kompilacji Resto.Front.Api.V6.dll i implementuje interfejs IFrontPlugin z tej kompilacji, jest to wtyczka V6.
Zakłada się, że wtyczka V6 korzysta z interfejsu programu V6.
Jednak jeśli jest to konieczne, wtyczka może jednocześnie korzystać ze wszystkich wspieranych wersji API.
Biorąc pod uwagę, że począwszy od V6, przestrzenie nazw nie zawierają numeru wersji API, aby uniknąć kolizji między typami o tych samych nazwach z różnych zestawów, należy użyć extern alias.
Na przykład, aby uzyskać dostęp do operacji dostępnej tylko w V7Preview2 używając wtyczki V6, wystarczy dodać odwołanie do kompilacji Resto.Front.Api.V7Preview2.dll i pobrać usługę Resto.Front.Api.V7Preview2.IOperationService z PluginContext.Services.
Ważne: nie zaleca się implementowania interfejsów IFrontPlugin różnych wersji — taka wtyczka nie zostanie załadowana.
Status wersji API i odpowiadające im wersje Syrve Instance
| Wersja | Status | Wydanie | Usunięcie |
|---|---|---|---|
| V1 | Nie wspierana | 3.1 | 3.8 |
| V2 | Nie wspierana | 3.3 | 4.3 |
| V3 | Nie wspierana | 3.8 | 5.4 |
| V4 | Nie wspierana | 4.3 | 7.0 |
| V5 | Nie wspierana | 5.4 | 8.0 |
| V6Preview4 | Nie wspierana | 6.41 | 7.0 |
| V6Preview5 | Nie wspierana | 6.4 | 7.1 |
| V6 | Przestarzała | 7.0 | |
| V7Preview1 | Nie wspierana | 7.1 | 7.4 |
| V7Preview2 | Nie wspierana | 7.3.52 | 7.4 |
| V7Preview3 | Nie wspierana | 7.3 | 7.5 |
| V7Preview4 | Nie wspierana | 7.4 | 7.6 |
| V7Preview5 | Nie wspierana | 7.5 | 7.7 |
| V7Preview6 | Nie wspierana | 7.6 | 7.9 |
| V7Preview7 | Przestarzała | 7.7 | 8.53 |
| V7 | Stabilna | 7.9 | 9.5 |
| V8Preview1 | Nie wspierana | 8.0 | 8.2 |
| V8Preview2 | Nie wspierana | 8.1 | 8.3 |
| V8Preview3 | Nie wspierana | 8.2 | 8.4 |
| V8Preview44 | Aktualna | 8.3 | 8.6 |
| V8Preview5 | Aktualna | 8.4 | 8.7 |
| V8Preview6 | Aktualna | 8.5 | 8.8 |
| V8Preview7 | W fazie rozwoju | 8.6 | 8.9 |
| V8 | W fazie rozwoju | 8.7 | 10.3 |
| V9Preview1 | 8.8 | 9.1 | |
| V9Preview2 | 8.9 | 9.2 | |
| V9Preview3 | 9.0 | 9.3 | |
| V9Preview4 | 9.1 | 9.4 | |
| V9Preview5 | 9.2 | 9.5 | |
| V9Preview6 | 9.3 | 9.6 | |
| V9Preview7 | 9.4 | 9.7 | |
| V9 | 9.5 | ||
| V10Preview1 | 9.6 | 9.9 | |
| V10Preview2 | 9.7 | 10.0 | |
| V10Preview3 | 9.8 | 10.1 | |
| V10Preview4 | 9.9 | 10.2 | |
| V10Preview5 | 10.0 | 10.3 | |
| V10Preview6 | 10.1 | 10.4 | |
| V10Preview7 | 10.2 | 10.5 | |
| V10 | 10.3 | ||
| {:.mbtablestyle} | |||
| 1 V6Preview4 była wersją eksperymentalną, została wydana na początku cyklu rozwoju Syrve Office 6.4. Ponadto pominięto wersje V6Preview6 i V6Preview7 — zamiast nich wydano wersję LTS V6. | |||
| 2 Wersja V7Preview2 została wydana późno, jako 7.3.5 (zamiast 7.2). | |||
| 3 Wsparcie dla V7Preview7 zostało przedłużone do włącznie 8.4 z powodu problemów z automatyczną aktualizacją wtyczek z V7Preview7 do V7. | |||
| 4 Okres życia wersji podglądowych począwszy od V8Preview4 został wydłużony o jedną wersję Syrve Instance. | |||
| Począwszy od wersji Syrve Instance 8.5, cykl wsparcia dla wersji Preview zostaje wydłużony: wersja V8Preview4, która została wydana w 8.3, zostanie usunięta dopiero w 8.6, czyli będzie wspierana w wersjach 8.3, 8.4, 8.5. |
Wsteczna kompatybilność
Wsteczna kompatybilność zapewnia, że wtyczka opracowana dla konkretnej wersji API będzie działać tak samo z dowolnymi wersjami Syrve Office, które obsługują tę wersję API.
Kompatybilność programu
Kompatybilność programu zabrania jakichkolwiek zmian w publicznym interfejsie: struktury danych, sygnatury metod i tym podobne muszą pozostać niezmienione. Jasne jest, że jeśli jakakolwiek publiczna klasa lub metoda zostanie usunięta, wtyczka przestanie się kompilować z nowym SDK, podczas gdy wtyczka skompilowana dla poprzedniego SDK ulegnie awarii podczas działania (TypeLoadException, MissingMethodException i tak dalej). Mogą wystąpić inne mniej oczywiste problemy z wsteczną kompatybilnością. Jednakże, jeśli pominąć niektóre rzadkie przypadki, dodanie nowej klasy, funkcji lub metody może przebiegać dość płynnie. Umożliwia to korzystanie z nowych funkcji bez oczekiwania na nowe wydanie. W związku z tym przyjęto nową politykę:
- W wersjach LTS nie powinno się wprowadzać żadnych zmian po ich wydaniu, ponieważ każda publiczna zmiana jest zmianą łamiącą kompatybilność,
- Wersje Preview mogą zawierać potencjalnie wstecznie kompatybilne zmiany w publicznym interfejsie.
Zmiany w zachowaniu
Zasadniczo zmiany w zachowaniu wydanych wersji API nie są dozwolone. Jeśli funkcja działa w określonych warunkach, będzie nadal działać, w przeciwnym razie nie. Destrukcyjne przypadki użycia API, gdy pewne konsekwencje powodują większe szkody niż awaria wstecznej kompatybilności, mogą stanowić wyjątek od tej zasady. Na przykład, jeśli luki w API powodują, że błędy wtyczki prowadzą do uszkodzenia danych lub awarii Syrve POS, API zostanie odpowiednio zabezpieczone. Nie będzie to uważane za zmianę w zachowaniu, ponieważ poprawnie działające wtyczki nie odczują różnicy.
Okres wsparcia
Okres wsparcia dla dowolnej wersji API oznacza czas, w którym wydawane są aktualizacje Syrve Office obsługujące tę wersję API. Produkty Syrve Office nie mają ograniczeń kalendarzowych dotyczących używania jakiejkolwiek wersji API. Wszystkie wersje API obsługiwane przez konkretną wersję Syrve Office są wspierane na stałe. Dlatego jeśli użytkownik Syrve Office nie aktualizuje systemu, może korzystać z wtyczek tak długo, jak to możliwe. W praktyce jednak użytkownik musi aktualizować Syrve RMS, aby dostosować się do zmian w prawie, korzystać z nowych funkcji lub naprawić błędy, co oznacza, że twórca wtyczek musi na czas udostępniać aktualizacje kompatybilne z nowymi wersjami API.