Git and the libraries for newbies


#1

Please could we have a newbies tutorial on the Git (and Python) workflow when contributing to the official libraries?

Briefly on why people should help grow the official libs instead of everyone recreating their own versions. Briefly the intent of the KLC.

How to use Git to work with a local copy of the libraries. Then after creating/adding various symbols, associated footprints and 3d models: Using kicad-library-utils. Using Git to do pull requests. Also where does GitHub fit in?


#2

could a github wiki-page be used for a collaborative tutorial/FAQ?
just sitting down and writing a tutorial in one go that covers all of that is too much for most people.
if the tutorial is a wiki-page or on github then working on smaller sections piece by piece is much better (at least for me).


#3

It should really not be the responsibly of kicad to explain either git or github. There are enough good tutorials out there already for that.

Github simply hosts the git server and provides a nice web interface. (There are plans to transfer all of the kicad resources to a gitlab server on a cern server. But that will take some time.)


The stuff about creating symbols and footprints is well documented in the official kicad documentation and we have two additional tutorials here on the forum. (4 if you count the stuff about making new libraries)

The library management also has a tutorial here on the forum. This one even explains how a custom setup connected directly to github could look like: Library management in KiCad version 5 (Focused on how to get github changes into kicad. The other way round is not explained there.)


#4

I now also copy the answer i gave on github (was created before i knew that you did not use a local git setup for your pull requests.):

To make separate pull requests you need to have one branch per contribution.

I am assuming you have the official library repo added as a second remote and called it upstream:

git fetch upstream  # get the state of the official repo
git checkout upstream/master  # change to the current head of the official repo
git checkout -b new_sensible_branch_name # create a new branch from that state
git push --set-upstream origin new_sensible_branch_name # push that new branch to github
# after you made your changes work normally with
git add -u # or git add list_of_files
git commit # enter sensible commit message as usual
git push # push your changes online

if you then are requested to do some changes you would need to checkout the correct branch and then do your changes.

git checkout branch_connected_to_pull_request
# do your changes
git add -u # or again git add file_list
git commit # detail what you changed in the commit message
git push # push your fixes to github (will automatically appear in the pull request)

To add the official repo as a second remote called upstream (one time setup):

git remote add upstream https://github.com/KiCad/kicad-footprints.git

#5

Okay I’ve started a wiki page over at Git (and Python) workflow when contributing to the official KiCad libraries, that I’ll try to follow.