1. Innføring

Dette dokumentet inneholder informasjon for utviklere om infrastrukturen til LinuxCNC og beskriver beste praksis for å bidra med programkode og dokumentasjonsoppdateringer i LinuxCNC-prosjektet.

Gjennomgående i dette dokumentet betyr "kildekode" både kildekoden til programmene og bibliotekene, samt kildeteksten for dokumentasjonen.

2. Kommunikasjon blant LinuxCNC-utviklerne

De to viktigste måtene prosjektutviklerne kommuniserer med hverandre er:

3. Source Forge-prosjektet til LinuxCNC

Vi bruker Sourceforge til epostlister.

4. Versjonskontrollsystemet git

Alt av kildekode i LinuxCNC vedlikeholdes i versjonskontrollsystemet git.

4.1. Offisielt git-depot for LinuxCNC

Det offisielle LinuxCNC-git-depotet er på https://github.com/LinuxCNC/linuxcnc/linuxcnc/

Andre kan hente en skrivebeskyttet kopi av LinuxCNC-kildekodetreet via git:

git clone https://github.com/linuxcnc/linuxcnc linuxcnc-dev

Hvis du er en utvikler med tilgang til å sende inn endringer, følg instruksene til github for å sette opp et depot som du kan sende inn fra.

Merk at clone-kommandoen legger det lokale LinuxCNC-depotet i en mappe ved navn linuxcnc-dev, i stedet for forvalgt linuxcnc. Årsaken er at LinuxCNC-programvaren i utgangspunktet forventer oppsett og G-kodeprogrammer i en mappe ved navn $HOME/linuxcnc, og det blir forvirrende hvis katalogen også er git-depoet.

Issues and pull requests (abbreviated PRs) are welcome on GitHub: https://github.com/LinuxCNC/linuxcnc/issues https://github.com/LinuxCNC/linuxcnc/pulls

4.2. Bruk av Git i LinuxCNC-prosjektet

We use the "merging upwards" and "topic branches" git workflows described here:

Vi har en utviklingsgren ved navn master, og en eller flere stabile grener med navn som 2.6 og 2.7 som markerer versjonsnummeret til utgavene vi lager fra grenen.

Feilfikser går i den eldste aktuelle stabile grenen, og denne grenen flettes så inn i neste nyere stabile gren, og så videre opp til master. Den som sjekker inn feilfiksen kan gjøre flettingen selv, eller kan overlate flettingen til noen andre.

New features generally go in the master branch, but some kinds of features (specifically well isolated device drivers and documentation) may (at the discretion of the stable branch release managers) go into a stable branch and get merged up just like bugfixes do.

4.3. git tutorials

There are many excellent, free git tutorials on the internet.

The first place to look is probably the "gittutorial" manpage. This manpage is accessible by running "man gittutorial" in a terminal (if you have the git manpages installed). The gittutorial and its follow-on documentation are also available online here:

For a more thorough documentation of git see the "Pro Git" book: https://git-scm.com/book

Another online tutorial that has been recommended is "Git for the Lazy": https://wiki.spheredev.org/index.php/Git_for_the_lazy

5. Oversikt over prosessen

Høynivåoversikten over hvordan bidra med kildekodeendringer ser slik ut:

  • Kommuniser med prosjektutviklerne og la oss vite hva du jobber med. Forklar hva du gjør og hvorfor.

  • Klon git-depotet.

  • Make your changes in a local branch.

  • Oppdatering av dokumentasjon og writing tests er en viktig del av å legge til en ny egenskap. Ellers vil ikke andre vite om din utvidelse og ingen vil oppdage det hvis den nye egenskapen din knekkes av andre endringer.

  • Del endringene dine med andre prosjektutviklere på en av disse måtene:

    • Send grenen din til github og lag en github-endringsforespørsel på https://github.com/linuxcnc/linuxcnc (dette krever en github-konto), eller

    • Send grenen din til et offentlig tilgjengelig git-depot (slik som github eller din eget offentlig tilgjengelige tjener etc) og del adressen med emc-developers-epostlisten, eller

    • Send endringene dine på epost til LinuxCNC-utviklernes epostliste (<emc-developers@lists.sourceforge.net>) (bruk git format-patch for å lage endringsbeskrivelsen).

  • Spre ordet om endringen din:

    • Forklar hvilket problem den løser og hvorfor den bør tas med i LinuxCNC.

    • Vær mottakelig for spørsmål og tilbakemeldinger fra utviklerfellesskapet.

    • Det er ikke uvanlig at et endringsforslag må gjennom flere revisjoner før det tas inn.

6. git-oppsett

In order to be considered for inclusion in the LinuxCNC source, commits must have correct Author fields identifying the author of the commit. A good way to ensure this is to set your global git config:

git config --global user.name "Ditt Fulle Navn"
git config --global user.email "you@example.com"

Use your real name (not a handle), and use an unobfuscated e-mail address.

7. Effective use of git

7.1. Sjekk inn innhold

Keep your commits small and to the point. Each commit should accomplish one logical change to the repo.

7.2. Write good commit messages

Keep commit messages around 72 columns wide (so that in a default-size terminal window, they don’t wrap when shown by git log).

Use the first line as a summary of the intent of the change (almost like the subject line of an e-mail). Follow it with a blank line, then a longer message explaining the change. Example:

7.3. Commit to the proper branch

Bugfixes should go on the oldest applicable branch. New features should go in the master branch. If you’re not sure where a change belongs, ask on irc or on the mailing list.

7.4. Use multiple commits to organize changes

When appropriate, organize your changes into a branch (a series of commits) where each commit is a logical step towards your ultimate goal. For example, first factor out some complex code into a new function. Then, in a second commit, fix an underlying bug. Then, in the third commit, add a new feature which is made easier by the refactoring and which would not have worked without fixing that bug.

This is helpful to reviewers, because it is easier to see that the "factor out code into new function" step was right when there aren’t other edits mixed in; it’s easier to see that the bug is fixed when the change that fixes it is separate from the new feature; and so on.

7.5. Follow the style of the surrounding code

Make an effort to follow the prevailing indentation style of surrounding code. In particular, changes to whitespace make it harder for other developers to track changes over time. When reformatting code must be done, do it as a commit separate from any semantic changes.

7.6. Get rid of RTAPI_SUCCESS, use 0 instead

The test "retval < 0" should feel familiar; it’s the same kind of test you use in userspace (returns -1 for error) and in kernel space (returns -ERRNO for error).

7.7. Simplify complicated history before sharing with fellow developers

With git, it’s possible to record every edit and false start as a separate commit. This is very convenient as a way to create checkpoints during development, but often you don’t want to share these false starts with others.

Git provides two main ways to clean history, both of which can be done freely before you share the change:

git commit --amend lets you make additional changes to the last thing you committed, optionally modifying the commit message as well. Use this if you realized right away that you left something out of the commit, or if you typo’d the commit message.

git rebase --interactive upstream-branch lets you go back through each commit made since you forked your feature branch from the upstream branch, possibly editing commits, dropping commits, or squashing (combining) commits with others. Rebase can also be used to split individual commits into multiple new commits.

7.8. Make sure every commit builds

If your change consists of several patches, git rebase -i may be used to reorder these patches into a sequence of commits which more clearly lays out the steps of your work. A potential consequence of reordering patches is that one might get dependencies wrong - for instance, introducing a use of a variable, and the declaration of that variable only follows in a later patch.

While the branch HEAD will build, not every commit might build in such a case. That breaks git bisect - something somebody else might use later on to find the commit which introduced a bug. So beyond making sure your branch builds, it is important to assure every single commit builds as well.

There’s an automatic way to check a branch for each commit being buildable - see https://dustin.sallings.org/2010/03/28/git-test-sequence.html and the code at https://github.com/dustin/bindir/blob/master/git-test-sequence. Use as follows (in this case testing every commit from origin/master to HEAD, including running regression tests):

cd linuxcnc-dev
git-test-sequence origin/master..  '(cd src && make && ../scripts/runtests)'

This will either report All is well or Broke on <commit>

7.9. Renaming files

Please use the ability to rename files very cautiously. Like running indent on single files, renames still make it more difficult to follow changes over time. At a minimum, you should seek consensus on irc or the mailing list that the rename is an improvement.

7.10. Prefer "rebase"

Use git pull --rebase instead of bare git pull in order to keep a nice linear history. When you rebase, you always retain your work as revisions that are ahead of origin/master, so you can do things like git format-patch them to share with others without pushing to the central repository.

8. Oversettelser

LinuxCNC-prosjektet bruker gettext for å oversette progamvaren til mange språk. Vi ønsker bidra velkommen og det er enkelt å hjelpe til på dette området: Du trenger ikke vite noe om programmering, og du trenger ikke installere noe spesiell oversetterprogramvare eller noe annen programvare.

Den enkleste måte å hjelpe til med oversettelser er ved å bruke Weblate, en fri programvarenettjeneste. Vårt oversetterprosjekt er her:

Dokumentasjonen om hvordan bruke Weblate er her: https://docs.weblate.org/en/latest/user/basic.html

9. Andre måter å bidra

Det er mange måter å bidra til LinuxCNC som ikke er omtalt i dette dokumentet. Dette inkluderer:

  • Svare på spørsmål på forumet, epostlistene og IRC

  • Rapportere feil til feilhåndterer, epostlister og på IRC

  • Bidra med å teste eksperimentelle egenskaper