Udvikling/Deltag

From The Document Foundation Wiki
Jump to: navigation, search
This page is a translated version of the page Development/GetInvolved and the translation is 100% complete.

Other languages:
dansk • ‎English • ‎italiano • ‎日本語

Udviklere og brugere kan bidrage til udvikling af LibreOffice på mange måder og alle er velkomne i projektet.

Brugere kan fx hjælpe til med udviklingen ved at beta-teste udgivelser af softwaren, reportere og teste fejl, skrive dokumentation, bidrage til skabeloner, opdatere synonym- og retskrivningsordbøger, oversætte til dit modersmål, tilføje billeder, sprede budskabet og promovere LibreOffice.

På denne sde koncentrerer vi os om udviklere. Husk på, at vi er åbne for udviklere på alle niveauer, vi har nogle få "kerne"-udviklere (det betyder i grunden folk, der har været der siden historien begyndte), men de fleste af os er relativt nye. LibreOffice er en af de største, ældste og mest kendte (som OpenOffice) frie software-pakker. Hvis du studerer eller leder efter ansættelse, er det et stort plus på dit CV at kunne skrive "Jeg har arbejdet for LibreOffice". Du kan, efter aftale, bruge vor ledende udviklingsmentor som reference. Udviklere hjælper til med at forbedre LibreOffices kodebase. I begyndelsen kan den enorme kodebase virke skræmmende, men dokumentationen forbedres og du vil blive støttet af det eksisterende udviklingsteam. Denne side til hjælpe dig med at få sendt din første rettelse. Hjælpe dig med at få overblik (husk at alle EasyHacks har kode-pointere).

Trin-for-trin vejledning for nye udviklere

Det er let at blive overvældet af LibreOffices størrelse og kompleksitet. Kilden er skrevet i mange forskellige sprog og formater  — C, C++, Java, Bash, JavaScript, Python, Perl, SQL, Test, XML — og består af rundt regnet 102.000 filer (alle lokaliseringer undtaget) med 36.000.000 tekstlinjer (7.000.000 linjer kildekode)

Ingen forstår hele koden i detaljer, men vi har mange kerneudviklere, som hver for sig kender en del af koden til bunds. Denne trin for trin vejledning viser en let vej fra "ønsker at bidrage" til succesfuldt at have den første rettelse flettet ind i master(filen). Hvis du ønsker at hjælpe eller behøver flere oplysninger, tøv venligst ikke med at kontakte vor Udviklingsmentor

Forbindelse til vore kommunikationskanaler

Vores hovedkommunikationskanal er libreoffice@lists.freedesktop.org; vi anbefaler dig at abonnere på den. Du kan også følge listen online på libreoffice@lists.freedesktop.org;

Vi vil holde kildekoden fri til brug for enhver. Derfor er det vigtigt at du sender (brug venligst Emnet: <dit navn> license statement) en licenserklæring til libreoffice@lists.freedesktop.org med teksten:

   All of my past & future contributions to LibreOffice may be
   licensed under the MPLv2/LGPLv3+ dual license.

En mindre variation for at passe til din personlige smag er fint, så længe intention er klar. Du vil modtage en velkomstbesked som svar. Vi vedligeholder en liste over udviklere på vorwiki.

Send venligst ikke erklæringen før du sender dit første bidrag til gerrit og sørg for at du har tilladelse fra dine forældre!

Hvis du har brug for et hurtigt svar til et enkelt spørgsmål, kan du finde mange af os på IRC freenode #libreoffice-dev connect via webchat

Byg LibreOffice

For at udvikle har du brug for en lokal kopi af kildekoden. Hele koden findes i git

Windows

Windows-udviklere har brug for at hve Cygwin og andre værktøjer installeret. Det letteste er at bruge lode

Bemærk, at nogle folk oplever problemer med mappenavne under Windows (ligesom LO ikke kan finde mscvc.exe), se venligst her:

ret sti-problemer

et ord om antivirus-scanners

Når du programmerer anbefaler vi meget at du deaktiverer din virus-scanner (og selvfølgelig ikke surfer, mens den er deaktiveret).

Hvis du lader virus-scanneren være aktiv, skal du tilføje en undtagelsesliste, der mindst indholder

  • perl.exes
  • <git home>/workdir

eller mislykkes dit build. Vi har lægt mærke til, at en kørende virus-scanner under programmering ofte forlænger programmeringstiden, sometider med mere end 30%.

i nogle tilfælde er der et problem med realtids-beskyttelse af et kørende program.

Problemet her er, at AV scanner den kørende applikation og når kompileren forsøger at oprette det næste test-værktøj (med det samme test-navn), kan linkeren ikke skrive filen, fordi AV-scanneren blokerer denne fil. AV er langsommere, når test-værktøjet kører.

Der er rapporteret adskillige problemer under installationen i forhold til virus-scanneren, så det anbefales meget at deaktivere virus-scanneren, mens lode kører.

macOS

macOS kan opsættes på forskellige måder, når du bliver mere specialiseret, ønsker du måske en mere kompliceret opsætning, men for at komme i gang foreslår vi at følge Hurtig opsætning

Linux

Linux (de fleste varianter) kan sættes op med pakkeinstallatorer. Vi foreslår at du følger Programmering under Linux

Forbered indsendelse af rettelser

Når du først har kompileret LibreOffice med succes, er du klar til indsende rettelser. Vi bruger gerrit til at holde styr på rettelserne, så du har brug for at oprette en konto der. Følg denne gerrit guide til opsætning

Der er grundliggende to måder at indsende/arbejde med rettelser. Dem, der er fortrolige med Git review kan bruge det, men vi anbefaler et enklere værktøj ved navn logerrit.

Vær omhyggelig, når du indsender ændringer til undermoduler såsom Hjælp (og kun kloner Hjælp) eftersom gerrit-scriptet ikke er tilgængeligt og du måske ikke har gerrit-krogen installeret. Se opsætningstrin i Development/Submodules.

Find din første fejl at rette

Tillykke, du har nået den interessante del.

At rette den første fejl indebærer, at du lærer nye værktøjer og metoder, derfor har vi identificeret nogle lette fejl kaldet Easy_Hacks. Vi bruger bugzilla, hvor du har brug for at oprette en konto for at holde styr på rapporterede fejl.

Easy hacks er rigtige fejl, men kerne-udviklerne har tilføjet kode-pointere og sommetider tekst-hjælp, i stedet for bare at rette dem for at gøre det lettere for dig at rette fejlen. Vælg en fejl fra dit foretrukne programmeringssprog (se ovenfor), som interesserer dig EasyHacks efter sprog og færdighed. Som du ser, er der mange at vælge imellem. Vi anbefaler kategorien "Færdighedsniveau: Begynder" for at lade dig koncentrere dig om alle "hvordan gør jeg ....".

Når du først har valgt en fejl at rette, glem så venligst ikke at tildele den i bugzilla til dig selv, så andre kan se, at du arbejder på den. Hvis du vil arbejde på en af de generelle fejl (såsom at konvertere foo til xyz), lad venligst være med at tildele til dig selv, da mange kan arbejde på det parallelt. EasyHack bliver overvåget, så hvis der ikke er noget fremskridt efter en tid, fjerner vi tildelingen.

Selvfølgelig er der også andre udfordringer til senere:

Rette en fejl

Nogle praktiske råd, som vi pga. erfaring anbefaler, at du følger, er:

  • Foretag aldrig ændringer på din kopi af masterfilen - opret en gren i stedet.
  • Behold en særlig gren til hver fejl, og slet ikke grenen, før rettelsen er flettet ind.
  • Følg Kodetypografien (som fx plan for variabelnavne, osv.)
  • Hvis du opretter nye filer, brug venligst vores License-politik.
  • Undgå venligst større omformatering af koden i øjeblikket (ud over til nedenstående opgaver) - vi overvejer auto/magiske måder at gøre dette på på mellem til langt sigt
  • Opdater masterfilen, før du starter på en ny fejl (og kør make check for at bekræfte, at den kompilerer rent, før du foretager nogen ændringer).
  • Indsend inden rettelser, der er afhængige af hinanden, med mindre du bliver bedt om det. Ellers bliver dine rettelser umulige at flette ind.
  • Hvis din rettelse ikke er klar til at blive flettet ind, tildel den -2, så ved revisorerne, at der er arbejde undervejs.
  • Tålmodighed er en nøglen, korrekturlæsning tager tid og vi er alle frivillige, så forvent, at der går et par dage.

Foreslået arbejdsgang

1. Opdater master

Sørg for, at din masterfil er opdateret og virker. Hvis din masterfil er for gammel, løber du den risiko, at du ikke er stand til flette din ændring ind.

Som en tommelfingerregel skal du bruge kommandoerne herunder, hvis

  • din masterfil er mere end en uge gammel.
  • din nye fejlrettelse er afhængig af arbejder, som netop er blevet flettet ind.
./g pull -r
make
make check

!! make skal være 3.8.1 eller højere

Brug venligst kontakten-r, som er meget mere effektiv end simpelt træk. Masterfilen går ofte i stykker, men normalt kun i kort tid (indsendere reagerer normalt hurtigt, hvis de har lavet en forkert rettelse).

Når make afsluttes, ved du, at du har en fungerende masterfil, så hvis make går ned under kompileringen af din rettelse, skyldes det et problem et-eller-andet sted i din kode. make check kører alle testtilfælde og sikrer, at du har en fungerende version af LibreOffice.

2. Arbejd på en gren

Du kan blive bedt om at ændre din rettelse, og hvis du har oprettet og arbejdet på en særlig gren, vil det være meget let. Brug venligst en ny gren (fra masterfilen) til hver fejl, du arbejder på. Så snart rettelsen er blevet flettet ind, kan du slette grenen.

git checkout -b test1

Giv test1 det navn, du foretrækker.

3. Ret fejlen

Identificer problemet, ret koden, generer og afprøv en version. Husk at levere en enheds-test, når det er muligt for at verificere at problemet er løst.

Der findes et antal praktiske og hjælpsomme værktøjer

Husk nu at køre en git commit -a jævnligt. Det giver dig mulighed for let at opgive en del af din udvikling, hvis det skulle vise sig at være en forkert vej.

4. Indsend rettelsen

Det anbefales, at dine indsendelsebeskeder ligner denne:

   tdf#12345 <short developer description of change, not just the bug title>
   <empty line>
   <description of what the patch does, the more words the better others understand it later>
  • hvis der er en fejlrapport med forbindelse til indsendelsen, er det obligatorisk at starte første linje med en fejlhenvisning såsom tdf#12345 (se detaljer nedenfor)
  • brug resten af den første linje som en kortfattet sammendrag af dine ændringer. Maximumlængden på denne linje er 72 tegn.
  • brug nutid. fortæl, hvad ændringen gør. Vær skarp. Undgå "pynt" som streger og parenteser, som spilder plads.
  • Hvis du vil skrive mere tekst end det, der passer i den første linjer, er det obligatorisk at lade anden linje være blank
  • fra 3. linje forklarer du, hvad rettelsen gør og hvorfor, og hvis det ikke klart, også hvordan. Disse linjer skal højst være på 80 tegn, del i flere linjer, hvis din kommentar er længere. Her kan du også beskrive, hvordan koden virkede ukorrekt før ændringen.

Hvis din rettelse ordner en fejl, som allerede er registreret i Bugzilla, kan du drage fordel af automatiske fejl-beskeder, som udløses af indsendelsesmeddelelser. Når den første linje af indsendelsesmeddelelsen indeholder en henvisning til en fejl på formen tdf#12345, vil en tilsvarende kommentar automatisk blive tilføjet fejlrapporten, når ændringen sendes til depotet. Find flere oplysninger på annoncerings-tråden på mail-archive.com eller på fdo-listarchive.

Kontrollér, at dine ændringer ikke ødelægger automatisk testning.

make check

Nu kan du indsende ændringen til gerrit (se Forbered indsendelse af rettelser):

./logerrit submit master

Revision af din ændring

Din ændring vil typisk blive revideret i løbet af 1-2 dage. Du kan følge status på gerrit og du vil også modtage post, når der sker ændringer. (Bliv ikke bekymret, hvis Jenkins rapporter, at kun Windows-konstruktionen ikke ikke klarede den automatiske kompilering.)

Generelt kan der ske 3 ting i revisonen:

  • Indsenderen reviderede og testede ændringen med succes, og flettede den til masterfilen (tillykke)
  • Indsenderen har nogle kommentarer, som du er nødt til se på
  • Sommetider ødelægger ændringen en anden funktionalitet og er mærket som “Cannot merge”

I de sidste 2 tilfælde, skal du opdatere din ændring.

Brug af Code-Review og Verified

Hvis du kigger på din ændring på Gerrit, vil du se to statuskoder.

  • Code-Review
  • Verified

Korrekturlæserne, vort CI-system (jenkins) og muligvis dig selv, vil bruge disse to felter til at kvalificere ændringen.

Code-Review

kan markeres som -2, -1, 0, +1, +2

-2 skal anvendes af forfatteren for at signalere "igangværende arbejde". -2 forhindrer ændringen i at blive flettet og kun den, der har lavet markeringen -2, kan fjerne den.

Hvis du arbejder på en større ændring, er du meget velkommen til at uploade en ændring og markere den -2, for at se om den kompileres med succes på alle platforme

-1 bruges af korrekturlæseren, hvis der er ting i rettelsen, der skal ændres

0 bruges, når der skrives kommentarer, der ikke påvirker, om ændringen skal flettes eller ej.

+1 bruges af korrekturlæseren til at signalere, at rettelsen er OK, men korrekturlæseren ønsker en ekstra vurdering

+2 bruges af forfatteren til at signalere, at der ikke er brug for korrektur (dette kan kun gøres af kerneudviklerne, og skal bruges med forsigtighed) Den person, der fletter din rettelse, vil bruge +2 lige før fletningen, eftersom kun +2 kan flettes. Evnen til sætte markeringen +2 afhænger af korrekturlæserens push-rettigheder. Disse rettigheder tildels individuelt.

Bemærk, at din rettelse IKKE vil blive flettet, så længe der er ubesvarede -1 eller -2.

Verified

Kan markeres som -1, 0, +1

-1 bruges af CI-systemet, hvis konstruktionen fejler (bemærk, at der ikke altid er et problem med din rettelse, men kan skyldes en ødelagt masterfil).

-1 bruges af korrekturlæseren, hvis det ventede resultat ikke kan ses.

0 bruges, når der skrives kommentarer, der ikke påvirker, om ændringen skal flettes eller ej.

+1 bruges af CI-systemet, hvis konstruktionen sker med succes

+1 bruges af korrekturlæseren, når det ventede resultat er bekræftet.

Bemærk, at en rettelse IKKE bliver flettet, medmindre CI-systemet viser en vellykket konstruktion.

Opdater en rettelse

Tjek din gren

git checkout test1

foretag de nødvendige ændringer og test dem. Det er høfligt at kommentere de kodelinjer, du ikke vil ændre eller hvor du ikke er enig med indsenderen, dette gøres direkte i gerrit.

Når du er parat til at indsende igen, er det vigtigt, at du bruger —amend

git commit --amend -a

Vigtigt Brug ikke parameteren -m, da det vil slette gerrits rettelses-id. Lad git åbne en tekstbehandler, der lader dig redigere indsendelsesmeddelelsen (eller lad den være uændret). Mens du redigerer, skal du passe på ikke at fjerne/ændre den sidste linje med rettelses-id-et.

Dette vil sikre, at du opdaterer rettelsen i stedet for at genere en ny (med et nyt Change-id:)

Upload det nye rettelsessæt til gerrit

./logerrit submit master

Tillykke

Du har lavet en vellykket ændring til en af de mest populære open-source-pakker i verden.

Forsæt med at lave rettelser og du vil snart selv være committer.

Begynderetikette

Erfarne bidragsydere vil hjælpe dig med at finde løsninger på dine problemer, men der er forventninger og begrænsninger. Fjern-mentor og -fejlfinding er en større kognitiv belastning end at være fysisk til stede. Når du viser dig velforberedt, vil folk være mere motiverede for at hjælpe dig.

Generelle retningslinjer:

  • Når du bruger chatten: beskriv straks dit problem og bliv på kanalen i mindst en time.
  • Til at dele tekst med flere linjer på chatten bruger du en indsæt-tjeneste som den, der nævnes i kanalens emne.
  • Hvis du har problemer med netværksforbindelsen, fungerer postlisten bedre end chatten.
  • Hvis du arbejder med em kompleks flertrins opgave, er det en god ide tage personlige notater. De bliver meget nyttige, når du bliver spurgt om, hvad du foreløbig har lavet.
  • Når du har fået et svar, kvittér på en eller anden måde. Hvis du forsvinder uden et spor, bliver dine hjælpere chokerede.

Hvis du står over for et problem med git, indsendelse af rettelser eller opsætning af udviklingsmiljøet, er det bedst af følge disse trin:

  1. Prøv selv at finde vejledningen eller løsningen selv. Sommetider vil dine hjælpere også være nødt til at lede selv.
  2. Hvis din søgning lykkes, gør et forsøg på at følge instrukserne.
  3. Hvis du ikke fandt nogen instruktion eller blev hængende i anvendelse af dem, bed om hjælp.

Med disse slags vanskeligheder vil hjælperne med glæde prøve at løse hele dit problem for dig.

Hvis du løser et eassy hack, er det godt at huske på disse kendsgerninger og tips:

  • Der findes ikke noget enkelt dokument, der forklarer koden i klart sprog. Undervisningsmateriale er spredt over dias fra konferencepræsentationer, blogposter og wiki-sider.
  • Hyppigheden af kommentarer er mindre end ideel (du kan hjælpe!), så du må være forberedt på at læse kode.
  • Brug git grep og OpenGrok til at finde de definitioner og klasser, du løber på.
  • Undersøg også indsendelseshistorien for lignende emner andetsteds i kodebasen. OpenGrok's Annotate-kommando kan være oplysende i denne slags detektivarbejde.
  • Kør en debugger, mens du bruger LibreOffice, for at finde ud af, hvad der sker under motorhjelmen.
  • Gennemgå readme-filerne.

Hvis du beder nogen om at sige, hvordan man implementerer noget, vil du sandsynligvis blive mødt med tavshed. Easy hacks regnes for at være en læringsøvelse og mentorer ønsker ikke at ødelægge den. En foreslået implementering vil blive kommenteret i korrektursystemet.