En begyndervejledning til git - Hvad er en Changelog og hvordan man genererer den

Sig, at du er en udvikler, og at du bruger Git til et af dine projekter. Du vil dele de ændringer, du har foretaget med dine brugere, men du ved ikke hvordan. Nå, så er denne artikel noget for dig.

I den sidste del af denne serie delte jeg med dig, hvordan man skriver en god meddelelse.

Jeg gav dig et overblik over fordelene ved at skrive en god forpligtelse, og jeg nævnte muligheden for at generere en changelog.

I denne artikel lærer du, hvad en changelog er sammen med to måder at generere den på - en enkel og en sofistikeret.

Hvad er en changelog?

En changelog er en fil, der deler en kronologisk ordnet liste over de ændringer, du har foretaget på dit projekt. Det er ofte organiseret efter versionen med datoen efterfulgt af en liste over tilføjede, forbedrede og fjernede funktioner.

Globalt er der to måder at skrive en changelog på:

  • den sædvanlige måde: Opret en tekstfil og start med at tælle alle dine ændringer med en bestemt dato
  • udviklerens valg (alias den dovne mulighed): generer automatisk din changelog fra dine commit-meddelelser. Jeg har gode nyheder til dig - dette vil du lære i denne artikel!
“En changelog er en log eller registrering af alle bemærkelsesværdige ændringer foretaget i et projekt. Projektet er ofte et websted eller et softwareprojekt, og ændringsloggen inkluderer normalt registreringer af ændringer såsom fejlrettelser, nye funktioner osv. ” - Wikipedia

Hvorfor er det vigtigt?

Jeg tror, ​​selv nu spørger du dig selv, hvorfor det er vigtigt, og hvorfor du skal tage dig tid til at skabe det.

En changelog er en slags resumé af alle dine ændringer. Det skal være let at forstå både af brugerne, der bruger dit projekt, og udviklerne, der arbejder på det.

I en verden, hvor alt udvikler sig hurtigt, skal en bruger vide, om det websted / software, de bruger, ændrer sig. Du kan blive overrasket, men folk elsker at læse blogindlæg eller en opdateringsside på dit websted.

For en udvikler, for eksempel, hvis projektet er stort, kan det være interessant at vide, hvordan den software, de arbejder på, udvikler sig.

Eller hvis du arbejder på et open source-projekt, kan du finde en "CHANGELOG.md" -fil i GitHub-arkivet. Denne fil har til formål at informere bidragsydere om de seneste opdateringer om projektet.

Hvor finder vi dem?

Changelogs er overalt! Okay, de har ofte forskellige stilarter og placeringer, men de er bogstaveligt talt på hvert projekt.

Jeg oprettede en kort liste med et par steder, hvor du kan finde en changelog.

  • Et blogindlæg. En changelog kan leveres under en artikel, der deler de sidste funktioner punkt for punkt.
  • En "CHANGELOG.md" -fil i et GitHub-arkiv.
  • Et Changelog-afsnit på dit yndlingswebsted / software. Her er et eksempel med opgavestyringsværktøjet TickTick.
  • I "Hvad er nyt" på Android og IOS-butikken.

Changelog auto-generation

I denne del skal vi generere vores første changelog sammen.

Ved at udføre denne opgave forstår du, hvorfor det kan være nyttigt at begå ved at følge nogle regler.

En fremragende og eksplicit forpligtelse behøver ikke at blive ændret og kan føjes direkte til changelog.

Hvis du er interesseret i at generere en nødvendig fil uden personalisering eller forskønning, anbefaler jeg den første vej; ellers er den anden bedre.

Bemærk : Nogle websteder såsom Keep A Changelog forklarer, at du ikke kun skal foretage en ændringslog ved at kopiere og indsætte dine git-forpligtelser (se den enkle måde). Faktisk anbefaler jeg at prøve at undgå denne måde, hvis du arbejder på et professionelt produkt.

I dag er der dog nogle avancerede generatorer, der giver dig mulighed for at ændre dine git-logfiler til changelogs (se den sofistikerede måde).

Sådan genereres en changelog (den enkle måde)

Ved at bruge denne første måde har du ikke brug for nogen forudsætninger. Alt hvad du behøver er at skrive et par kommandoer inde i dit Git-arkiv.

Som en simpel påmindelse, når du skriver "git log", vises en liste over alle dine forpligtelser.

$ git log // Output commit f6986f8e52c1f889c8649ec75c5abac003102999 (HEAD -> master, origin/master, origin/HEAD) Author: Sam Katakouzinos  Date: Tue Mar 10 11:41:18 2020 +1100 docs(developers): commit message format typo Any line of the commit message cannot be longer *than* 100 characters! Closes #17006 commit ff963de73ab8913bce27a1e75ac01f53e8ece1d9 Author: Chives  Date: Thu Feb 6 19:05:57 2020 -0500 docs($aria): get the docs working for the service Closes #16945 commit 2b28c540ad7ebf4a9c3a6f108a9cb5b673d3712d Author: comet  Date: Mon Jan 27 19:49:55 2020 -0600 docs(*): fix spelling errors Closes #16942

Denne kommando kan tage et par parametre. Vi skal bruge dem til at ændre output og få en forbedret til at generere vores changelog.

Ved at skrive følgende kommando vil du have en output med en forpligtelse pr. Linje.

$ git log --oneline --decorate // Output f6986f8e5 (HEAD -> master, origin/master, origin/HEAD) docs(developers): commit message format typo ff963de73 docs($aria): get the docs working for the service 2b28c540a docs(*): fix spelling errors 68701efb9 chore(*): fix serving of URI-encoded files on code.angularjs.org c8a6e8450 chore(package): fix scripts for latest Node 10.x on Windows 0cd592f49 docs(angular.errorHandlingConfig): fix typo (wether --> whether) a4daf1f76 docs(angular.copy): fix `getter`/`setter` formatting be6a6d80e chore(*): update copyright year to 2020 36f17c926 docs: add mention to changelog ff5f782b2 docs: add mention to changelog 27460db1d docs: release notes for 1.7.9 add78e620 fix(angular.merge): do not merge __proto__ property

Det er bedre, men lad os se, hvad vi kan gøre med den følgende.

$ git log --pretty=”%s” // Output docs(developers): commit message format typo docs($aria): get the docs working for the service docs(*): fix spelling errors chore(*): fix serving of URI-encoded files on code.angularjs.org chore(package): fix scripts for latest Node 10.x on Windows docs(angular.errorHandlingConfig): fix typo (wether --> whether) docs(angular.copy): fix `getter`/`setter` formatting chore(*): update copyright year to 2020 docs: add mention to changelog docs: add mention to changelog docs: release notes for 1.7.9 fix(angular.merge): do not merge __proto__ property

Med denne kan du udskrive listen over forpligtelser med den ønskede stil.

“% S” svarer til selve forpligtelsestitlen. Du kan ændre strengen for at style din forpligtelse, som du vil.

I vores tilfælde vil vi oprette en liste.

$ git log --pretty="- %s" // Output - docs(developers): commit message format typo - docs($aria): get the docs working for the service - docs(*): fix spelling errors - chore(*): fix serving of URI-encoded files on code.angularjs.org - chore(package): fix scripts for latest Node 10.x on Windows - docs(angular.errorHandlingConfig): fix typo (wether --> whether) - docs(angular.copy): fix `getter`/`setter` formatting - chore(*): update copyright year to 2020 - docs: add mention to changelog - docs: add mention to changelog - docs: release notes for 1.7.9 - fix(angular.merge): do not merge __proto__ property

Du gjorde det! Du oprettede en simpel ændringslog.

Bemærk : Hvis du vil gå længere og gemme din changelog hurtigere: i stedet for at kopiere og indsætte resultatet i en fil, skal du omdirigere det til din terminal ved at skrive “git log --pretty =" -% s "> CHANGELOG.md”

Sådan genereres en changelog (den sofistikerede måde)

Forudsætninger

Vi skal nu udforske en sofistikeret måde at generere en changelog på. Ideen bag processen forbliver den samme, men denne gang skal vi bruge andre værktøjer til at hjælpe os.

Kan du huske, hvornår jeg i sidste del af denne serie skrev om Git-retningslinjerne?

Bemærk : Git-retningslinjer er et sæt regler for at skrive dine forpligtelser bedre. Disse retningslinjer hjælper dig med at tilføje struktur til dine forpligtelser.

Når du bruger en retningslinje til dit projekt, kan du bruge værktøjer til at generere en changelog. For det meste er disse værktøjer bedre, fordi de giver dig mulighed for at oprette en markdown-formateret changelog.

I dette eksempel skal vi bruge en simpel generator, der fungerer med de fleste af retningslinjerne. Dets navn er "generer-changelog", og det er tilgængeligt på NPM (Node Package Manager).

Dette værktøj vil skabe en stiliseret changelog, men det er ikke den med de fleste funktioner. Jeg besluttede at bruge det, fordi det er et glimrende eksempel for en nybegynder. Hvis du vil gå videre, henvises til listen over changelog-værktøjer nedenfor:

Her er et par værktøjer, du kan bruge:

  • Github Changelog Generator
  • Git Chglog
  • Auto-ændring
  • Konventionel ændring
Bemærk: Før du installerer værktøjet, skal du have NPM installeret på din computer. Hvis du ikke har det, inviterer jeg dig til at følge det officielle websted (det hjælper dig med at installere Node og NPM).

For at installere pakken på din computer skal du skrive følgende kommando i din terminal.

$ npm install generate-changelog -g 

Når du har gjort det, er det installeret!

Brugsvejledning

For at få denne pakke til at fungere, skal du følge retningslinjerne for brug af dette mønster - “type (kategori): beskrivelse [flag]”. I dette eksempel vil jeg bruge Angular.js GitHub-lageret.

Nu kan du skrive genereringskommandoen i din terminal inde i dit GitHub-lager.

$ changelog generate

En “CHANGELOG.md” -fil oprettes automatisk og udfyldes med dine logfiler i et markdown-format.

Du kan finde et eksempel på output (med en markdown-læser som GitHub) nedenfor.

Konklusion

Jeg håber, du kunne lide denne guide og nu forstår, hvordan du opretter en changelog til dit projekt. Jeg synes, det er en god måde at demonstrere, hvorfor du skal skrive gode forpligtelsesbeskeder.

Du er velkommen til at prøve andre changeloggeneratorer og sende mig resultatet!

Hvis du har spørgsmål eller feedback, så lad mig det vide.

Gå ikke glip af mit indhold ved at følge mig på Twitter og Instagram.

Du kan finde andre artikler som denne på min hjemmeside: herewecode.io.

Ønsker mere?

  • Hver uge får du et motiverende tilbud med nogle råd, en kort tutorial i et par dias og et udviklerbillede på Instagram.
  • Tilmeld dig nyhedsbrevet, og få de nyeste artikler, kurser, tutorials, tips, bøger, motivation og andet eksklusivt indhold.