Versionskontroll för öppen källkod: 10 steg

2025 Författare: John Day | [email protected]. Senast ändrad: 2025-01-23 15:11

Teamet på Brainbow har ett antal elektronikprojekt under vårt bälte, och vi ville dela vår process för att använda versionskontroll för att hantera vårt arbetsflöde för elektronisk design. Detta arbetsflöde har använts för stora och små projekt, från enkla tvåskiktsbrädor till komplexa 10-lagers behemoths, och är baserat på verktyg med öppen källkod. Förhoppningsvis kan andra anta vårt arbetsflöde själva och få fördelarna med versionskontroll för sina egna projekt. Men vilka fördelar kan versionskontroll erbjuda ett elektronikprojekt?

Steg 1: Varför versionskontrollera din elektronik?

Version Control (aka källkontroll eller revisionskontroll) är ett välkänt och allmänt antaget koncept inom mjukvaruteknik. Tanken bakom källkontroll spårar systematiskt ändringar som görs i källkoden för ett program eller en applikation. Om ändringar bryter programmet kan du återställa källkodfilerna till ett känt arbetsläge från tidigare. I praktiken tillåter källkontrollsystem dig att spåra historiken för en samling filer (vanligtvis källkodfilerna för ett datorprogram, webbplats, etc.) och visualisera och hantera ändringar av dessa filer.

Att spåra historien om förändringar i ett projekt verkar användbart för elektronikprojekt; om du gör ett misstag i kretsschemat eller använder fel komponentfotavtryck i PCB -layouten, skulle det vara trevligt att hålla reda på vilka misstag som gjordes och vilka korrigeringar som genomfördes i olika revideringar av ett projekt. Det skulle också vara användbart för andra beslutsfattare att se den historien och förstå sammanhanget och motivationen för olika förändringar.

Steg 2: Verktygen: KiCad och Git

Vi använder två huvudverktyg i detta projekt: versionskontrollsystemet (VCS) och elektronikdesignautomatiseringsprogrammet (EDA eller ECAD).

Det finns MÅNGA versionskontrollsystem där ute, men vi använder den distribuerade VCS Git. Vi använder den av flera anledningar, men nyckeln är att den är öppen källkod (kontrollera!), Enkel att använda (kontroll!) Och de facto-standard VCS för öppen källkod (kontrollera!). Vi kommer att använda Git som VCS för att spåra ändringarna i filerna som vårt ECAD -program använder. Denna instruerbara kräver inte bekantskap med Git, men allmän komfort med kommandoraden förutsätts. Jag kommer att försöka länka till användbara resurser för både Git och kommandoradsanvändning efter behov.

De flesta källkontrollsystem fungerar särskilt bra för textbaserade filer, så ett ECAD-program som använder textfiler skulle vara bra. Ange KiCad, öppen källkod "Cross Platform and Open Source Electronics Design Automation Suite" som stöds av forskare vid CERN. KiCad är också öppen källkod (check!), Lätt att använda (även om vissa inte håller med mig om det) och mycket kapabel för avancerat elektronikdesignarbete.

Steg 3: Installation

För att installera dessa program, följ instruktionerna från deras olika nedladdningssidor länkade nedan.

• KiCad är plattformsoberoende (och svindlande; deras nedladdningssida listar 13 operativsystem som stöds och erbjuder en nedladdning av källkod om ingen av dem passar dig). Använd den kicad-enhetliga standardinstallationen, inte den nattliga utvecklingsversionen. Se steg 4 för avancerade valfria detaljer om biblioteksinstallation.
• Git är också plattformsoberoende. Om jag använder Windows skulle jag rekommendera det imponerande Git for Windows-projektet för en mer användbar och komplett upplevelse.

Installationsdokumentationen som finns på båda dessa platser kommer att vara mer fullständig än någon beskrivning jag kan erbjuda här. När båda programmen har laddats ner och installerats kan du klona Brainbows projektmall från vårt Github -arkiv. Kommandot git clone tar strukturen `git clone {src directory} {target directory}`; för vårt projekt, använd `git clone https://github.com/builtbybrainbow/kicad-starter.git {target directory}`.

Kloning av en git repo är en speciell kopieringsform; när du klonar ett projekt får du en kopia av alla filer som ingår i repo samt hela Git-spårade historiken för projektet. Genom att klona vår repo får du en projektkatalog som redan är strukturerad med våra rekommendationer för användning av Git med KiCad. Vi kommer att täcka mer om projektstrukturen i steg 6, eller så kan du hoppa till steg 7 om du kliar i att börja jobba.

Några snabba hushållsuppgifter - kör `git remote rm origin 'för att ta bort länken till Github -projektet du klonade från. Kör också `git commit --amend --author =" John Doe "` och ersätt författarparametern med ditt namn och din e -postadress. Detta ändrar det sista åtagandet (som i detta fall också är det första åtagandet) och ändrar författaren till dig, snarare än Brainbow.

Steg 4: Installation Obs: KiCad Libraries

En snabb anteckning om KiCads bibliotekstruktur. KiCad tillhandahåller en uppsättning bibliotek som underhålls av utvecklarteamet för ett stort antal elektriska komponenter. Det finns tre huvudbibliotek:

• Schematiska symboler: Symboler som används för att representera elektroniska komponenter i en kretsschematisk ritning.
• PCB -fotavtryck: 2D -ritningar som representerar det faktiska fotavtrycket (kopparkuddar, silketryck, etc.) som ska användas när kretsen läggs ut på ett kretskort.
• 3D -modeller: 3D -modeller av elektroniska komponenter.

Dessa bibliotek laddas ner tillsammans med KiCad -programpaketen du just installerade. Du kan använda KiCad utan mer ansträngning. För "kraftanvändare" lagras dock källfilerna för biblioteken i ett git -arkiv på Github, så att användare som vill hålla sig uppdaterade med de senaste ändringarna kan klona bibliotekets repos till sin egen dator. Att spåra biblioteken med git har ett antal fördelar - du kan välja när du vill uppdatera dina bibliotek, och uppdateringar behöver bara införliva ändringar i filerna, snarare än att ladda ner hela uppsättningen biblioteksfiler igen. Du är dock ansvarig för att uppdatera biblioteken, vilket kan vara lätt att glömma.

Om du vill klona biblioteken beskriver den här webbplatsen de olika Github -repos som KiCad erbjuder. Git klonar biblioteken till din dator (ex: `git clone https:// github.com/KiCad/kicad-symbols.git`), öppna sedan KiCad, välj menyfältet" Inställningar "och klicka på" Konfigurera sökvägar … ". Detta låter dig berätta för KiCad katalogsökvägen för att leta efter varje bibliotek i. Dessa miljövariabler har som standard sökvägen till de bibliotek som installerats med KiCad -installationen. Jag noterade dessa värden så att jag kunde byta tillbaka till standardbiblioteken om det behövs. Sökvägen KICAD_SYMBOL_DIR ska peka på ditt klonade kicad-symbolbibliotek, KISYSMOD till det klonade kicad-footprints-biblioteket och KISYS3DMOD till det klonade kicad-packages3d-biblioteket.

När du vill uppdatera biblioteken kan du köra ett enkelt 'git pull' -kommando i bibliotekets repo som berättar för Git att kontrollera om det finns skillnader mellan din lokala kopia av bibliotekets repo och Githubs "fjärr" -repo och automatiskt uppdatera din lokal kopia för att införliva ändringar.

Steg 5: Git Fundamentals

Git är ett komplext och mångfacetterat program, med hela böcker som ägnas åt att behärska det. Det finns dock några enkla koncept som hjälper dig att förstå hur vi använder Git i vårt arbetsflöde.

Git spårar ändringar av filer med hjälp av en serie etapper. Normala ändringar sker i arbetskatalogen. När du är nöjd med de ändringar du har gjort i en serie filer lägger du till de filer som du har ändrat till mellanläggningsområdet. När du har gjort alla de ändringar du planerar och iscensatt alla filer du vill spåra i Git, överlåter du dessa ändringar till förvaret. Commits är i huvudsak ögonblicksbilder av filernas tillstånd i en repo vid en viss tidpunkt. Eftersom Git spårar ändringar i filer och lagrar dessa ändringar i åtaganden, kan du när som helst återställa ett projekt till det tillstånd det befann sig i vid varje tidigare åtagande.

Det finns mer komplexa ämnen, som förgreningar och fjärrkontroller, men vi behöver inte använda dessa för att få fördelarna med källkontroll. Allt vi behöver är att spåra ändringar i våra KiCad -designfiler med en rad åtaganden.

Steg 6: KiCad -projektstruktur

Låt oss titta närmare på strukturen för KiCad-Starter-projektet som du klonade tidigare. Det är uppdelat i ett antal underkataloger för enkel organisation:

• Krets: Den här mappen innehåller de faktiska KiCad -projektfilerna (schematisk, PCB, etc). Jag byter inte namn på den här mappen, men jag byter namn på alla filer inuti med namnet på projektet (Circuit.pro => ArduinoMini.pro).

  • Circuit.pro: KiCad -projektfilen
  • Circuit.sch: den schematiska filen KiCad.
  • Circuit.kicad_pcb: KiCad PCB -layoutfil.
• Dokumentation: Den här mappen är för lagring av dokumentation angående projektet. Vi har planer på att förbättra detta utrymme i framtiden, men för närvarande innehåller det en enkel README -fil. Använd den för att lagra anteckningar om projektet för framtida granskning.
• Tillverkning: I den här mappen kommer du att lagra de gerber -filer som de flesta fab -hus kommer att använda för att tillverka ditt kretskort. Vi använder den också för att lagra BOM -filer och andra dokument som kan behövas för tillverkning och montering.
• Bibliotek: Den här mappen är till för att lagra projektspecifika biblioteksfiler (vi täcker detta mer i några steg).

Du kanske också har lagt märke till några andra filer (särskilt om du 'ls -a' katalogen).. Git -katalogen är där Git gör sin magi och lagrar lagringshistoriken.. Gitignore -filen används för att berätta för Git vilka filer den ska ignorera och inte lagra i källkontroll. Dessa är mestadels backupfiler som KiCad genererar, eller några olika "genererade" filer, som nätlistor, som inte bör lagras i källkontroll eftersom de genereras från källan som är den schematiska filen.

Denna projektstruktur är bara en utgångspunkt. Du bör anpassa den efter dina behov och lägga till sektioner efter behov. I vissa projekt har vi inkluderat en mjukvara eller en mapp där vi lagrade modeller för 3D -utskrifter för projektet.

Steg 7: Använda Git för KiCad -projekt

Vi är äntligen redo att se hur vi använder Git för att spåra dina projekt. Denna instruktionsbok är inte avsedd att lära dig hur du använder KiCad (även om jag kan göra en i framtiden om det finns efterfrågan på det), så vi kommer att gå igenom några triviala exempel för att visa dig hur arbetsflödet fungerar. Det ska vara lätt att förstå hur man anpassar dessa idéer till ett riktigt projekt.

Öppna kicad-starter-katalogen och kör sedan 'git log' för att visa bindningshistoriken. Det borde finnas ett åtagande här, initialiseringen av repot av Brainbow. Att köra 'git status' berättar status för filer i din repo (ospårad, modifierad, borttagen, iscensatt).

För närvarande bör du inte ha några förändringar i din repo. Låt oss göra en förändring. Öppna KiCad -projektet och lägg till ett motstånd i schemat och spara sedan. Nu kör 'git status' bör visa att du har ändrat den schematiska filen, men inte har iscensatt dessa ändringar för commit ännu. Om du är nyfiken på vad KiCad exakt gjorde när du lade till motståndet kan du köra diff -kommandot på den modifierade filen 'git diff Circuit/Circuit.sch'. Detta markerar ändringarna mellan den aktuella versionen av filen i arbetskatalogen och filens tillstånd vid den senaste åtagandet.

Nu när vi har gjort en förändring, låt oss försöka göra den ändringen till vår projekthistoria. Vi måste flytta ändringarna från vår arbetskatalog till scenen. Detta flyttar faktiskt inte filerna i filsystemet, men är konceptuellt ett sätt att låta Git veta att du har gjort alla dina planerade ändringar för en viss fil och är redo att göra dessa ändringar. Till hjälp ger Git några tips när du kör `git status 'för nästa åtgärd. Lägg märke till meddelandet `(använd" git add … "för att uppdatera vad som kommer att göras)` under `Ändringar som inte är iscensatta för commit:`. Git berättar hur du ska flytta ändringarna till scenområdet. Kör 'git add Circuit/Circuit.sch' för att iscensätta ändringarna, sedan 'git status' för att se vad som hände. Nu ser vi den schematiska filen under ändringar som ska göras. Om du inte vill göra dessa ändringar ännu, erbjuder Git hjälpsamt ett annat tips: '(använd "git reset HEAD …" för att avinstallera) `. Vi vill göra dessa ändringar, så vi kör `git commit -m" Added resistor to schematic "`. Detta gör ändringarna med det medföljande meddelandet. Genom att köra git -loggen visas detta engagemang i projektets engagemangshistorik.

Några fler tips om åtaganden.

1. Förplikta dig inte för varje sparande. Engagera dig när du känner att du har nått en punkt där dina förändringar har stelnat något. Jag förbinder mig efter att jag avslutat en schematisk, inte efter varje komponenttillägg. Du vill inte heller begå alltför sällan, för att komma ihåg varför du gjorde de ändringar du gjorde 3 veckor senare kan vara svårt. Att räkna ut när man ska begå är lite av en konst, men du kommer att bli bekvämare när du använder Git mer.
2. Endast butikskälla (mestadels). Detta inkluderar projekt-, schematiska och layoutfiler samt projektspecifika bibliotek. Detta kan också innehålla dokumentationsfiler. Var försiktig när du lagrar härledda objekt eftersom de lätt kan synkroniseras med den ursprungliga källan, vilket kan orsaka huvudvärk senare. BOM- och gerberfiler synkroniseras särskilt lätt, så undviks bättre (även om mer detaljerad vägledning behandlas i steg 9).
3. Commit-meddelanden är mycket användbara, men välstrukturerade commit-meddelanden är ovärderliga. Denna utmärkta artikel ger några riktlinjer för att skriva tydliga, koncisa och användbara meddelanden. Det kan kräva att du använder en kommandorads textredigerare, vilket kan göra mig komplicerad för nybörjare ('git commit' utan alternativet -m meddelande öppnar en textredigerare). För de flesta rekommenderar jag Nano -redaktören. StackOverflow har en bra förklaring till hur du byter redigerare

Steg 8: Avancerat: Semantisk versionering för elektronik

För de äventyrliga själarna är följande tips avancerade idéer, hämtade från många timmars KiCad -utveckling. De är inte särskilt användbara för mindre projekt, men de kan verkligen spara dig sorg när dina projekt växer i komplexitet.

I mjukvara finns det ett begrepp Semantic Versioning (semver). Semver definierar en vanlig namngivningsmetodik för att identifiera programvaruversioner med "versionsnummer", efter ett mönster av "Major. Minor. Patch". För att citera semvers spec, avancerar du versionsnumret enligt följande ändringskategorier.

1. STOR version när du gör inkompatibla API -ändringar,
2. Mindre version när du lägger till funktionalitet på ett bakåtkompatibelt sätt,
3. PATCH-version när du gör bakåtkompatibla buggfixar.

Vi på Brainbow använder vår egen version av semver anpassad för att passa behoven hos hårdvaruprojekt. Vår specifikation följer samma "Major. Minor. Patch" -mönster, även om våra definitioner av vilka förändringar som faller under vilken kategori uppenbarligen skiljer sig åt.

1. STOR version: används för betydande förändringar av kretsens kärnfunktion (t.ex. byte av processor från ATmegaa till ESP8266).
2. Mindre version: används för komponentswappar som kan påverka kretsdriften (ex: SPI-blixtbyte med stiftkompatibel del som kan ha en annan kommandoset) eller tillägg av några mindre tilläggsfunktioner (ex: extra temperatursensor).
3. PATCH -version: används för mindre buggfixar som inte kommer att ändra kretsfunktionen (t.ex. justering av silkscreen, mindre justering av spårlayout, enkla komponentbyten som 0603 kondensator till 0805).

I hårdvarusemver uppdateras versionsnumret endast vid tillverkning (precis som i programvara ändras versionsnummer bara med utgåvor, inte varje enskild förpliktelse till ett projekt). Som ett resultat har många projekt låga versionsnummer. Vi har ännu inte använt mer än fyra större versioner av ett projekt.

Bortsett från fördelarna med konsekvens och begriplighet du får från att byta till ett väldefinierat namngivningssystem, får du också fördelar med firmware-kompatibilitet och kundnöjdhet. Firmware kan skrivas samtidigt som man tar hänsyn till vilken version av kortet det är inriktat på, och det kan vara lättare att felsöka varför ett visst program inte fungerar på ett visst kort ("rätt, 2.4.1 -firmware körs inte på 1.2 styrelser eftersom vi inte har … "). Kunderna har också dragit nytta av vår hårdvarusemver eftersom kundservice och felsökning är mycket enklare med en definierad standard.

Steg 9: Avancerat: Användning av hårdvarusemantisk versionering

För att använda hårdvarusemver i dina egna projekt använder vi en Git -funktion som kallas tagging. När du först tillverkar ett kort är det 1.0.0 -versionen av det kortet. Se till att du har gjort alla ändringar i ditt projekt och kör sedan 'git tag -a v1.0.0'. Detta öppnar en redaktör så att du kan skriva ett anteckningsmeddelande för den här taggen (mycket lik ett bindande meddelande). Jag innehåller detaljer om tillverkningen (vem som tillverkade kretskortet, som monterade kortet), vilket kan vara användbar information senare.

Release -taggen läggs till i engagemangshistoriken och indikerar filernas tillstånd vid tillverkningen 1.0.0. Detta kan vara särskilt användbart flera revideringar senare när du behöver återgå till denna punkt för felsökning. Utan en specifik release -tagg kan det vara svårt att räkna ut vilket åtagande som var det senaste vid tillverkningstillfället. En tagg med 1.0.0 (och 1.1, 1.1.1, etc) låter dig ange att dessa specifika källfiler var de som användes i en viss tillverkningskörning.

En anteckning om Gerbers. Vissa fantastiska hus kräver gerber -filer för att göra ditt bräde, och du kan generera dem med KiCad. Dessa är härledda objekt, genererade från källkoden.kicad_pcb, och vi har normalt inte versionskontroll härledda filer. Vi på Brainbow lagrar inte gerber i versionskontroll UNDANTAG för när vi taggar en release. När vi är redo att bygga genererar vi gerberfilerna, lagrar dem i Fabrication -mappen och åtar och taggar. Sedan tar vi bort gerberna och begår radering. Det kan tyckas lite förvirrande till en början, men det säkerställer att normalt bara lagrar källfiler, och de märkta utgåvorna lagrar också de exakta filerna som används för att tillverka korten. Detta har visat sig vara mycket användbart för att spåra tillverkningsfel veckor senare.

Steg 10: Nästa steg

Förhoppningsvis har denna introduktion lärt dig nog att börja använda versionskontroll på dina egna elektronikprojekt. Vi kom inte till några av de mer avancerade ämnena, som versionskontroll för bibliotek som delas mellan projekt eller funktioner. Ändå är versionskontroll som att äta dina grönsaker: du får kanske inte det du tycker du borde, men varje bit du får räknas.

Brainbow arbetar med en mer detaljerad guide till några av de mer avancerade funktionerna i vårt arbetsflöde. Vi hoppas kunna publicera det någon gång under de närmaste månaderna. Följ oss här på Instructables, så meddelar vi dig när du kan läsa den.

Tack för att du läste, och vi kan inte vänta med att se vad du gör!