Blog Changeloop

Notatki wydania w praktyce

Dwie rzeczy, o których dużo myślimy: jak pisać notatki wydania, które ktoś przeczyta, i jak przestać ręcznie prowadzić changelog. Bez newslettera, bez rejestracji. Same teksty.

  • Testy alfa i beta: różnice i kiedy uruchomić każdy

    Testy alfa i beta w porównaniu: kto testuje, jak gotowy jest build, beta zamknięta i otwarta, kryteria wyjścia oraz zbieranie opinii testerów.

    Pętla feedbacku6 min czytania

  • Co to jest hotfix? Znaczenie, hotfix a patch, jak go wydać

    Hotfix to pilna poprawka wydana poza zwykłym cyklem wydań. Co oznacza ten termin, czym różni się od patcha lub bugfixa i jak wydać go bezpiecznie.

    Inżynieria5 min czytania

  • Model Kano: sortuj prośby o funkcje według emocji klientów

    Model Kano dzieli funkcje na obowiązkowe, wydajnościowe i zachwycające dzięki ankiecie z dwoma pytaniami. Jak użyć go przy prośbach o funkcje.

    Pętla feedbacku5 min czytania

  • Release candidate (RC): co oznacza i jak go poprowadzić

    Release candidate to build wydawany jako finalna wersja, jeśli testy nie znajdą blokera. Miejsce RC po becie, wersjonowanie i kryteria wyjścia.

    Inżynieria4 min czytania

  • Scoring RICE: wzór, przykład i typowe pułapki

    Scoring RICE szereguje pomysły według zasięgu, wpływu, pewności i wysiłku. Wzór, przykład na czterech funkcjach, skale i błędy zniekształcające wynik.

    Pętla feedbacku4 min czytania

  • CHANGELOG.md: co w nim jest i jak trzymać go aktualnym

    CHANGELOG.md to zapis dla czytelnika tego, co zmieniło się w każdej wersji. Potrzebne sekcje, pełny przykład i jeden nawyk, który utrzymuje plik aktualnym.

    Inżynieria5 min czytania

  • GitHub release notes: wygenerujcie je, potem zredagujcie

    GitHub szkicuje release notes ze scalonych pull requestów jednym kliknięciem. Co zawiera szkic, jak kształtuje go release.yml i jak go zredagować.

    Inżynieria6 min czytania

  • Jak zbudować roadmapę produktu na podstawie feedbacku

    Jak zbudować roadmapę produktu w sześciu krokach, zaczynając od próśb, które już macie. Grupowanie, ranking, pewność i przeglądy, by pozostała prawdziwa.

    Pętla feedbacku5 min czytania

  • Szablon roadmapy produktu: pola do skopiowania

    Szablon roadmapy produktu to tabela ze stałymi polami dla każdej pozycji. Skopiuj wersję z sześcioma polami, zobacz ją wypełnioną i sprawdź, co wyciąć.

    Pętla feedbacku5 min czytania

  • Wersjonowanie REST API: URL, nagłówek czy query, co pasuje

    Wersjonowanie REST API umieszcza wersję w ścieżce, nagłówku albo query stringu. Co każda opcja znaczy dla wywołujących, cache'y i ogłoszeń, z przykładami.

    Zmiany w API5 min czytania

  • Release notes oprogramowania: czym są i co w nich zawrzeć

    Release notes oprogramowania mówią, co zmieniło się w wersji, kogo dotyczy i co zrobić. Cztery rodzaje, co zawrzeć i przykład krok po kroku.

    Notatki wydania w praktyce4 min czytania

  • Release notes poprawek błędów: jak pisać użyteczne wpisy

    Release notes poprawek błędów działają, gdy wpis nazywa objaw, kogo dotknął i co robić dalej. Przepisane przykłady oraz zasady dla luk i utraty danych.

    Notatki wydania w praktyce6 min czytania

  • Jak prosić klientów o feedback w produkcie software'owym

    Zadajcie jedno konkretne pytanie zaraz po akcji użytkownika, tam gdzie pracuje. Gotowe sformułowania na każdą chwilę i złe prośby, których unikać.

    Pętla feedbacku6 min czytania

  • Przykłady roadmapy produktu: sześć formatów i ich wady

    Sześć przykładów roadmapy produktu z realistycznymi pozycjami: Now/Next/Later, kwartalna, tematyczna, wynikowa, publiczna i wydań. Komu służą, jak zawodzą.

    Pętla feedbacku6 min czytania

  • Proces zarządzania wydaniami dla zespołów wydających często

    Proces zarządzania wydaniami w siedmiu krokach, z właścicielem i kryteriami wyjścia dla każdego, plus metryki DORA i jeden dodatkowy wskaźnik do śledzenia.

    Inżynieria7 min czytania

  • Przykłady release notes na każdy rodzaj zmiany

    Przykłady release notes dla funkcji, poprawki, zmiany łamiącej, luki bezpieczeństwa, deprecacji, noty w sklepie i wewnętrznej, z uzasadnieniem.

    Notatki wydania w praktyce6 min czytania

  • Wersjonowanie API Stripe: jak działa i co z niego skopiować

    Wersjonowanie API Stripe przypina każde konto do wersji z datą i pozwala nadpisać ją w żądaniu. Jak działa, ile kosztuje i co może skopiować małe API.

    Zmiany w API6 min czytania

  • Kto pisze changelog, i kto powinien

    Kto pisze changelog? Autorka PR wie, co się zmieniło, PM wie, dlaczego to ważne. Żadna sama nie napisze dobrego wpisu, a domyślny wybór postarza changelog.

    Inżynieria5 min czytania

  • Awaryjne release notes: pisanie pod prawdziwą presją

    Wydanie po incydencie potrzebuje notatek pisanych w minuty, nie dni, a zwykły proces zakłada czas, którego nie macie. Co zostawić w notatkach, co wyciąć.

    Notatki wydania w praktyce4 min czytania

  • Zmiany łamiące w Protobuf: co przetrwa na wire

    Zmiany łamiące w Protobuf dzieją się na wire, nie w URL. Część zmian pól gRPC jest darmowa, inne po cichu łamią klientów, a w diffie wyglądają tak samo.

    Zmiany w API6 min czytania

  • Formaty plików changeloga: JSON, YAML czy zwykły Markdown

    Format pliku changeloga decyduje, czy zasili stronę i widżet, czy przeczyta go tylko człowiek. Markdown, JSON i YAML kosztują zupełnie coś innego.

    Inżynieria5 min czytania

  • Duplikaty próśb o funkcje: scalanie bez utraty głosu

    Grupowanie duplikatów próśb o funkcje chroni liczbę. Nieostrożne scalanie traci sformułowanie, które czyniło jedną z nich użyteczną, to mniejsza strata.

    Pętla feedbacku5 min czytania

  • Deprecacja GraphQL bez numeru wersji

    GraphQL nie ma v1 ani v2 w URL-u. Pola są deprecjonowane jedno po drugim dyrektywą, na jednym wspólnym schemacie, co zmienia, co jest winien changelog.

    Zmiany w API5 min czytania

  • Jak napisać przewodnik migracji API

    Przewodnik migracji API zamienia niekompatybilną zmianę w listę kontrolną zamiast awarii. Czego potrzebuje, kiedy go publikować i czemu wpis nie wystarczy.

    Zmiany w API4 min czytania

  • Wymagaj wpisu w changelogu w GitHub Actions: workflow

    Check changelogu w GitHub Actions odrzuca merge bez wpisu, bo krok zależny od pamiętania zawodzi według wzorca. Do tego: co taki check psuje.

    Inżynieria5 min czytania

  • Jak odrzucić prośbę o funkcję, nie tracąc klientki

    Zamykanie pętli zwykle oznacza powiedzenie komuś, że coś wydano. Trudniejsza połowa to powiedzieć nie, w sposób, który nie zepsuje relacji z klientką.

    Pętla feedbacku4 min czytania

  • Release notes dla feature flagów: co i kiedy napisać

    Release notes dla feature flagów muszą odróżnić merge od wydania, bo z flagą to nie to samo. Zamknięcie pętli za wcześnie ogłasza funkcję niewidoczną.

    Pętla feedbacku5 min czytania

  • Jak śledzić prośby o funkcje, nie gubiąc ich

    Śledzenie próśb o funkcje zawodzi zwykle na dwa sposoby: prośby nigdzie nie trafiają albo trafiają tam, gdzie nikt nie zagląda. System, który przetrwa oba.

    Pętla feedbacku5 min czytania

  • Prośba o funkcję a zgłoszenie błędu: jak je odróżnić

    Zgłoszenie do supportu proszące o nowe ustawienie może być obejściem ukrytego błędu. Zła etykieta wysyła je do niewłaściwej właścicielki i kolejki.

    Pętla feedbacku4 min czytania

  • Zgłoszenia do supportu vs. prośby o funkcje: czemu ufać?

    Zgłoszenie do supportu i tablica próśb o funkcje mierzą różne rzeczy, a traktowanie skoku w jednym jako w drugim daje pewne siebie, błędne priorytety.

    Pętla feedbacku4 min czytania

  • Tagi git vs wydania GitHub vs changelog: różnice

    Tag git, wydanie i wpis w changelogu to trzy zapisy jednego zdarzenia. Mieszanie ich sprawia, że changelog dryfuje. Jak te trzy powinny się zgadzać.

    Inżynieria5 min czytania

  • Wewnętrzne changelogi API: co się zmienia dla innego zespołu

    Publiczny changelog API ma odbiorców, do których nie da się dotrzeć bezpośrednio. Wewnętrzny ma odbiorców dwa piętra dalej, i to zmienia, co się im należy.

    Zmiany w API5 min czytania

  • Wewnętrzne notatki wydania: kto jeszcze musi wiedzieć

    Support i sprzedaż zwykle dowiadują się o premierze od zdezorientowanego klienta. Wewnętrzne notatki wydania to naprawiają, w innej formie niż klienckie.

    Notatki wydania w praktyce5 min czytania

  • Release notes aplikacji: limity App Store i Google Play

    Release notes w App Store mają do 4000 znaków, w Google Play 500, a oba pokazują kilka linijek bez linków. Co ucina limit i jak ciąć świadomie.

    Notatki wydania w praktyce4 min czytania

  • Changelogi w monorepo: jeden, czy jeden na pakiet?

    Monorepo może mieć jeden changelog dla całego repo albo jeden na pakiet, a zły wybór sprawia, że każde wydanie jest zbyt hałaśliwe albo zbyt rozproszone.

    Inżynieria5 min czytania

  • Ogłoszenie nowej funkcji: wzory i jak je napisać

    Większość ogłoszeń funkcji umiera w kanale, którego nikt nie czyta dwa razy. Gdzie ogłaszać, co powiedzieć najpierw, i kogo trzeba dosięgnąć.

    Notatki wydania w praktyce5 min czytania

  • Priorytetyzacja rosnącej liczby próśb o funkcje

    Śledzony backlog wciąż zostawia trudne pytanie otwarte: która prośba idzie pierwsza. Ramy, które działają, gdzie każde zawodzi, i co ukrywa liczba głosów.

    Pętla feedbacku5 min czytania

  • Release notes enterprise: co się zmienia dla jednego konta

    Release notes enterprise dla klienta na prywatnym buildzie muszą pasować do jego instancji. Złe dopasowanie ujawnia roadmapę albo myli jego supportu.

    Notatki wydania w praktyce4 min czytania

  • Semantic versioning a changelog: co znaczy każdy skok

    Semantic versioning mówi, jak bardzo wydanie może zaboleć, zanim ktoś przeczyta słowo z changeloga. Co obiecuje każda cyfra i co jest winny wpis.

    Inżynieria5 min czytania

  • Nagłówek Sunset w API i kiedy go wysyłać

    Nagłówek Sunset w API mówi klientowi, kiedy wersja przestanie odpowiadać, inaczej niż powiadomienie o deprecacji. Co obejmuje RFC 8594 i co daje brownout.

    Zmiany w API5 min czytania

  • Changelogi webhooków: zmiana łamiąca bez prośby

    Zmiana payloadu webhooka psuje się po cichu, bo nikt nie może jej odrzucić. Co czyni zmianę payloadu łamiącą, i jak nadać jej wersję krok po kroku.

    Zmiany w API5 min czytania

  • Co to jest changelog? Definicja i przykładowy wpis

    Changelog to datowany zapis zmian w produkcie, napisany dla osób, których dotyczą. Definicja, przykładowy wpis i gotowy do skopiowania szablon wpisu.

    Notatki wydania w praktyce5 min czytania

  • Changelog API: co publikować i kto to czyta

    Changelog API czytają osoby decydujące, czy ich kod będzie działał za miesiąc. Co każdy wpis im zawdzięcza, gdzie mieszka i jak się subskrybuje.

    Zmiany w API6 min czytania

  • Publiczna strona changeloga: jak zbudować taką do śledzenia

    Strona changeloga jest warta zbudowania, gdy ktoś na nią wraca. Gdzie powinna mieszkać, czego potrzebuje wpis, strumienie i markup, i gdzie pasuje widżet.

    Inżynieria5 min czytania

  • Szablon e-maila o aktualizacji produktu, który się czyta

    E-mail o aktualizacji produktu, który się czyta, trafił do kogoś, kto o niego prosił. Szablon, cztery typy e-maili, skuteczne tematy, segmentacja i zgoda.

    Notatki wydania w praktyce5 min czytania

  • Deprecacja API: harmonogram, powiadomienie, RFC 9745

    Deprecacja to obietnica z datą. Harmonogram, szablon powiadomienia, nagłówki odpowiedzi, i krok, który powstrzymuje sunset przed staniem się incydentem.

    Zmiany w API6 min czytania

  • Najlepsze praktyki wersjonowania API, dla wywołujących

    Wersjonujcie tylko to, co łamie kompatybilność, umieśćcie wersję tam, gdzie ją widzą wywołujący, i trzymajcie starą do daty. Cztery schematy porównane.

    Zmiany w API6 min czytania

  • Co to jest breaking change? Co się liczy i jak go wydać

    Zmiana łamiąca kompatybilność to każda, której poprawny wywołujący by nie przetrwał. Co się liczy, co nie, jak ją wykryć w CI i bezpiecznie wydać.

    Zmiany w API9 min czytania

  • Zamykanie pętli feedbacku od strony changelogu

    Pętla feedbacku zamyka się, gdy proszący wie: wydane. Pętla w czterech krokach, gdzie się psuje, i dlaczego changelog to właściwe miejsce, by ją zamknąć.

    Pętla feedbacku7 min czytania

  • Szablon prośby o funkcję, który staje się changelogiem

    Prośba o funkcję jest użyteczna tylko, jeśli da się ją odnaleźć przy wydaniu. Szablon, etykiety, które ją kierują, i pola, które później czyta changelog.

    Pętla feedbacku6 min czytania

  • Publiczna roadmapa z waszego trackera issue, trzy kolumny

    Publiczna roadmapa to obietnica na przyszłość. Trzymajcie ją małą, zasilajcie z waszych issue, i przesuwajcie każdy element etykietą na jego issue.

    Pętla feedbacku5 min czytania

  • Automatyzacja changelogu: co automatyzować, a czego nie

    Automatyzujcie zbieranie, formatowanie i publikację. Nie automatyzujcie selekcji ani sformułowania. Gdzie leży granica i co się dzieje, gdy się przesuwa.

    Inżynieria6 min czytania

  • Changelog vs release notes: jaka jest różnica?

    Changelog to ciągły rejestr dla kogoś, kto czegoś szuka. Release notes to wyselekcjonowana wiadomość dla kogoś, kto decyduje, czy go to obchodzi.

    Notatki wydania w praktyce5 min czytania

  • Od conventional commits do changelogu

    Conventional commits sprawiają, że changelog da się wyprowadzić, ale nie że jest czytelny. Co daje ta konwencja, gdzie się zatrzymuje i jak wypełnić lukę.

    Inżynieria5 min czytania

  • Jak pisać release notes, które ludzie faktycznie czytają

    «Poprawki błędów i usprawnienia wydajności» to nie release note. Pytanie, na które musi odpowiedzieć każdy wpis, i przepisanie prawdziwego przykładu.

    Notatki wydania w praktyce6 min czytania

  • Keep a Changelog: wyjaśnienie i szablon CHANGELOG.md

    Keep a Changelog to specyfikacja na jedną stronę, czytana w dziesięć minut. Wdrożenie to miejsce, gdzie zespoły od niej odchodzą. Co mówi, co zostawia.

    Inżynieria5 min czytania

  • Najlepsze praktyki release notes, które mają znaczenie

    Większość list najlepszych praktyk to porady stylistyczne. Te zmieniają zachowanie czytelnika, plus trzy popularne, które są czystym kultem cargo.

    Notatki wydania w praktyce5 min czytania