Changelog šablona

Programinės įrangos projekto pasikeitimų žurnalo šablono, atitinkančio „Keep a Changelog“ konvencijas.

# „Changelog Template“: svarbiausias įrankių rinkinys profesionaliai projektų dokumentacijai Programinės įrangos projekto priežiūra – tai ne tik kodo rašymas, bet ir informavimas apie darbo eigą vartotojams, bendradarbiams ir sau pačiam ateityje. Vis dėlto daugelis kūrėjų CHANGELOG.md failo atnaujinimą laiko antraeiliu darbu arba išleidimo įkarštyje apie jį visiškai pamiršta. „Changelog Template“ yra „Chrome“ plėtinys, sukurtas užpildyti šią spragą: jis suteikia supaprastintą, intuityvų ir profesionalų darbo procesą, skirtą kokybiškiems, pramonės standartus atitinkantiems pakeitimų žurnalams (angl. changelog) kurti. ## Pagrindinė paskirtis: geresnė komunikacija naudojant „Keep a Changelog“ principus „Changelog Template“ sukurtas siekiant padėti programinės įrangos projektams laikytis „Keep a Changelog“ konvencijų. Tinkamas pakeitimų žurnalas – tai kuruojamas, chronologine tvarka išdėstytas svarbių projekto pakeitimų sąrašas kiekvienai versijai. Tai nėra tiesiog „git commit“ žinučių sąrašas; tai žmonėms skirtas dokumentas. Naudodamiesi šiuo plėtiniu užtikrinate, kad projekto istorija būtų skaitoma, organizuota ir naudinga. Nesvarbu, ar tvarkote nedidelį asmeninį projektą, didelę atvirojo kodo biblioteką ar vidinių įrankių rinkinį, „Changelog Template“ suteikia struktūrą, kurios reikia skaidrumui ir profesionalumui palaikyti, neapsunkinant kūrimo ciklo. ## Standartizuotas formatas, kuriuo galite pasitikėti Plėtinys griežtai atitinka standartinį pakeitimų žurnalo formatą, todėl dokumentacija atrodo profesionaliai ir išlieka suderinama su platesne ekosistema. Kiekvienas jūsų sukurtas įrašas priskiriamas vienam iš šešių standartinių tipų, kuriuos rekomenduoja „Keep a Changelog“ projektas: 1. **Added (Pridėta):** naujoms funkcijoms, kurios plečia programinės įrangos galimybes. 2. **Changed (Pakeista):** esamos funkcionalumo dalies pakeitimams, kurie keičia programos veikimą. 3. **Deprecated (Pasenę):** netrukus pašalinamoms funkcijoms, įspėjant vartotojus apie būtinybę migruoti. 4. **Removed (Pašalinta):** funkcijoms, kurios oficialiai pašalintos iš kodo bazės. 5. **Fixed (Pataisyta):** klaidų ištaisymams, kurie sprendžia problemas ir gerina stabilumą. 6. **Security (Saugumas):** kritinėms pataisoms, skirtoms spręsti saugumo spragas. Šis klasifikavimas padeda vartotojams greitai peržvelgti jūsų išleidimo pastabas ir rasti būtent tai, ko jiems reikia—nesvarbu, ar jie ieško naujų įrankių, ar tikrina, ar konkreti klaida buvo ištaisyta. ## Patarimai, kaip rašyti paveikius įrašus Gero pakeitimų žurnalo įrašo rašymas yra menas. Tam reikia subalansuoti techninį tikslumą su prieinamumu. „Changelog Template“ ne tik suteikia teksto lauką, bet ir pateikia kontekstą bei gaires, reikalingas svarbiems įrašams kurti. Mes skatiname laikytis trijų paprastų taisyklių: - **Vartokite trumpus sakinius:** būkite glausti. Vienas aiškus punktas įraše yra geriau nei tanki pastraipa. - **Naudokite būtojo laiko formą:** aprašote tai, *kas pasikeitė* (pvz., „Pagerintas paieškos veikimas“, o ne „Pagerinti paieškos veikimą“). - **Žiūrėkite iš vartotojo perspektyvos:** rašykite žmogui, naudojančiam jūsų programinę įrangą, o ne tam, kuris parašė kodą. Užuot sakę „Pertvarkytas SQL užklausų optimizatorius“, sakykite „Pagerintas paieškos našumas 50 %“. Plėtinys netgi padeda su techniniais aspektais—automatiškai prideda didžiąsias raides įrašų pradžioje ir užtikrina, kad jie baigtųsi tašku, jei patys pamirštumėte. ## Funkcijų kupina darbo sritis „Changelog Template“ turi daugybę funkcijų, kurios dokumentaciją paverčia natūralia darbo proceso dalimi: ### 1. Greitas įrašų kūrimas Skirtukas „Create“ (Sukurti) yra jūsų pagrindinė darbo vieta. Pasirinkite pakeitimo tipą, įveskite įrašą ir spustelėkite „Add to Unreleased“ (Pridėti prie neišleistų). Taip paprasta. Nebereikia perjunginėti konteksto tarp IDE ir Markdown failo vien tam, kad užsirašytumėte greitą atnaujinimą. ### 2. Nuolatinis „Unreleased“ (neišleistų) skilties valdymas Viena galingiausių gero pakeitimų žurnalo funkcijų yra „Unreleased“ skiltis. Ji veikia kaip tarpinė vieta visiems pakeitimams, kuriuos atlikote nuo paskutinės oficialios versijos. „Changelog Template“ tvarko šią skiltį už jus, išsaugodamas įrašus vietinėje saugykloje, kad jie būtų pasiekiami vos tik atidarius plėtinį. ### 3. Semantinio versijavimo (SemVer) nuoroda Versijavimas neturėtų būti spėlionės. Mūsų skirtuke „Reference“ (Nuorodos) pateikiamas greitas vadovas apie semantinį versijavimą (SemVer), padedantis nuspręsti, ar kitas jūsų išleidimas turėtų būti pagrindinė (Major), šalutinė (Minor) ar pataisos (Patch) versija: - **MAJOR (PAGRINDINĖ):** nesuderinamiems API pakeitimams. - **MINOR (ŠALUTINĖ):** naujoms funkcijoms, kurios atgaline tvarka suderinamos. - **PATCH (PATAISA):** atgaline tvarka suderinamiems klaidų ištaisymams. ### 4. Automatizavimo įrankių nuorodos Komandoms, pasirengusioms žengti toliau, pateikiame nuorodas į pramonės standartus atitinkančius automatizavimo įrankius, tokius kaip „standard-version“, „release-it“ ir „semantic-release“. Šie įrankiai veikia kartu su mūsų plėtinio sugeneruotu Markdown formatu ir automatizuoja visą jūsų išleidimo procesą. ### 5. Kopijavimas vienu spustelėjimu ir Markdown eksportavimas Kai būsite pasiruošę atnaujinti failą, vienu spustelėjimu galėsite nukopijuoti „Unreleased“ skiltį kaip suformatuotą Markdown tekstą. Reikia pradėti naują projektą? Naudokite mūsų „Full CHANGELOG.md Starter Template“ (pilną CHANGELOG.md pradinį šabloną), kad sugeneruotumėte visą pagrindinį failą su reikiamomis antraštėmis ir nuorodomis. ## Kodėl svarbus geras pakeitimų žurnalas Gerai tvarkomas pakeitimų žurnalas yra daugiau nei tik atnaujinimų sąrašas; tai sveiko, brandaus projekto ženklas. Jis sukuria **skaidrumą**, parodydamas vartotojams, kad projektas yra aktyviai prižiūrimas. Jis palengvina **komunikaciją**, išryškindamas svarbius pakeitimus, kurie kitu atveju būtų pasimetę tarp šimtų „commit“ žinučių. Visų pirma, tai parodo **profesionalumą**. Kai vartotojas mato tvarkingą, organizuotą CHANGELOG.md failą, jis žino, kad gali pasitikėti projektu ir jį kuriančiu programuotoju. ## Kam tai skirta? - **Individualiems kūrėjams:** išlaikykite asmeninius projektus tvarkingus ir išvengite klausimo „ką aš padariau prieš tris mėnesius?“. - **Mažoms komandoms:** užtikrinkite, kad visi žinotų apie projekto pažangą, be būtinybės naudoti sudėtingas „Jira“ lentas kiekvienam smulkiam atnaujinimui. - **Atvirojo kodo bendradarbiams:** padarykite savo projektą patrauklesnį naujiems vartotojams pateikdami aiškias, lengvai skaitomas išleidimo pastabas. ## Lengva naudoti: jokios sąrankos, jokių rūpesčių „Changelog Template“ sukurtas taip, kad būtų nepastebimas, kol jo neprireiks. Nereikia sudėtingos sąrankos, nereikia kurti išorinių paskyrų ar valdyti API raktų. Jis naudoja „Chrome“ vietinę saugyklą, kad jūsų duomenys būtų privatūs ir pasiekiami tik jūsų kompiuteryje. Vartotojo sąsaja yra minimalistinė ir prisitaikanti, puikiai telpanti į naršyklės šoninę juostą ar iššokančią sritį. Neleiskite savo projekto dokumentacijai likti nuošalyje. Pradėkite naudoti „Changelog Template“ šiandien ir suteikite savo programinei įrangai profesionalią istoriją, kurios ji nusipelnė.