Changeloop

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.

  • 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

  • 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

  • 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żynieria6 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 praktyce5 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 API5 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

  • Check changelogu dla GitHub Actions

    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żynieria4 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

  • Kiedy prośba o funkcję jest naprawdę zgłoszeniem błędu

    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 feedbacku5 min czytania

  • Tagi git, wydania i twój changelog

    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

  • 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

  • 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 praktyce4 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

  • Release notes dla aplikacji mobilnych: co ucina limit

    App Store i Play Store dają kilka widocznych linijek i żadnych linków. To, co działa w web-owym changelogu, łamie się przy takim ciasnym budżecie.

    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

  • Jak ogłosić nową funkcję (bez ciszy)

    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 praktyce4 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 praktyce5 min czytania

  • Semantic versioning a twój changelog

    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

  • 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

  • Changelog: co to jest? Z przykładowym wpisem

    Changelog to datowany zapis zmian w produkcie. Przykładowy wpis, czym różni się od release notes, commit logu i roadmapy oraz gdzie powinien się znaleźć.

    Notatki wydania w praktyce5 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

  • 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

  • Jak zbudować stronę changeloga, którą się śledzi

    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

  • Jak deprecjonować API, nie tracąc programistów

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

    Zmiany w API5 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

  • Zmiany łamiące kompatybilność: co się liczy i jak je 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 API8 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 feedbacku5 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, i jej granice

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

    Inżynieria5 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 praktyce5 min czytania

  • Keep a Changelog, naprawdę wdrożony

    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