Git (and Python) workflow when contributing to the official KiCad libraries: Difference between revisions
(Created page with "This description of the '''Git (and Python) workflow when contributing to the official KiCad libraries''' is intended as a simple walk-through how-to for users new to KiCad...") |
No edit summary |
||
(5 intermediate revisions by the same user not shown) | |||
Line 5: | Line 5: | ||
== The KLC == |
== The KLC == |
||
The KiCad Library Convention (KLC) is a set of requirements for contributing to the official KiCad libraries.<ref>[http://kicad |
The KiCad Library Convention (KLC) is a set of requirements for contributing to the official KiCad libraries.<ref>[http://kicad.org/libraries/klc/ KiCad Library Convention], v3.0.17</ref> |
||
The things that are really important still need to be hand checked. This is the main work that library maintainers do. For example the pin numbers, names and types still needs to be compared to the datasheet, for footprints a dimension check is also required.<ref name="cont-parts"/> |
The things that are really important still need to be hand checked. This is the main work that library maintainers do. For example the pin numbers, names and types still needs to be compared to the datasheet, for footprints a dimension check is also required.<ref name="cont-parts"/> |
||
Line 22: | Line 22: | ||
Use schlib/checklib.py to check KLC compliance of schematic symbol libraries. |
Use schlib/checklib.py to check KLC compliance of schematic symbol libraries. |
||
== GitHub == |
== GitHub (out of date, now hosted at GitLab) == |
||
[[GitHub]] simply hosts a Git server and provides a nice web interface.<ref name="git4newbs">[https://forum.kicad.info/t/git-and-the-libraries-for-newbies/15010 Git and the libraries for newbies], KiCad.info Forums, Feb 2019</ref> The official KiCad libraries are hosted on GitHub. |
[[GitHub]] simply hosts a Git server and provides a nice web interface.<ref name="git4newbs">[https://forum.kicad.info/t/git-and-the-libraries-for-newbies/15010 Git and the libraries for newbies], KiCad.info Forums, Feb 2019</ref> The official KiCad libraries are hosted on GitHub. |
||
Line 54: | Line 54: | ||
The command line is the only place you can run ''all'' Git commands, most of the GUIs implement only a partial subset of Git functionality for simplicity. If you know how to run the command-line version, you can probably also figure out how to run the GUI version, while the opposite is not necessarily true.<ref>[https://git-scm.com/book/en/v2/Getting-Started-The-Command-Line Getting Started - The Command Line], Pro Git by Scott Chacon and Ben Straub</ref> |
The command line is the only place you can run ''all'' Git commands, most of the GUIs implement only a partial subset of Git functionality for simplicity. If you know how to run the command-line version, you can probably also figure out how to run the GUI version, while the opposite is not necessarily true.<ref>[https://git-scm.com/book/en/v2/Getting-Started-The-Command-Line Getting Started - The Command Line], Pro Git by Scott Chacon and Ben Straub</ref> |
||
=== Initial setup === |
|||
The first thing to do is to set your user name and email address, every Git commit will use this information. Use the git config command with the --global option this only needs to be done once:<ref name="atl">[https://www.atlassian.com/git/tutorials/setting-up-a-repository Setting up a repository], atlassian.com</ref><ref>[https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup Getting Started - First-Time Git Setup], git-scm.com</ref> |
|||
To setup the user name |
|||
<syntaxhighlight lang="linux-config"> |
|||
git config --global user.name "John Smith" |
|||
</syntaxhighlight> |
|||
To setup the user email address |
|||
<syntaxhighlight lang="linux-config"> |
|||
git config --global user.email john@example.com |
|||
</syntaxhighlight> |
|||
To check the user name |
|||
<syntaxhighlight lang="linux-config"> |
|||
git config user.name |
|||
</syntaxhighlight> |
|||
To check the user email address |
|||
<syntaxhighlight lang="linux-config"> |
|||
git config user.email |
|||
</syntaxhighlight> |
|||
=== Usage (e.g. for footprints) === |
=== Usage (e.g. for footprints) === |
||
Line 78: | Line 99: | ||
</syntaxhighlight> |
</syntaxhighlight> |
||
Add the official KiCad repo as another remote. This takes care of keeping all branches up-to-date between your fork ("origin") and the KiCad repo ("upstream"). This only needs to be done once: |
Add the official KiCad repo as another remote. This takes care of keeping all branches up-to-date between your downstream repository or fork ("origin") and the KiCad repo ("upstream"). This only needs to be done once:<ref name="atl"/><ref name="howto">[https://medium.com/sweetmeat/how-to-keep-a-downstream-git-repository-current-with-upstream-repository-changes-10b76fad6d97 How to keep a downstream git repository current with upstream repository changes]</ref> |
||
<syntaxhighlight lang="linux-config"> |
<syntaxhighlight lang="linux-config"> |
||
git remote add upstream https://github.com/KiCad/kicad-footprints.git |
git remote add upstream https://github.com/KiCad/kicad-footprints.git |
||
Line 123: | Line 144: | ||
git push # push your fixes to GitHub (will automatically appear in the pull request) |
git push # push your fixes to GitHub (will automatically appear in the pull request) |
||
</syntaxhighlight><ref name="git4newbs"/><ref name="">[https://forum.kicad.info/t/workflow-for-better-kicad-library-contribution-git-kicad/10593/3 Workflow for better KiCad library contribution (Git + KiCad)], KiCad.info Forums, May 2018</ref> |
</syntaxhighlight><ref name="git4newbs"/><ref name="">[https://forum.kicad.info/t/workflow-for-better-kicad-library-contribution-git-kicad/10593/3 Workflow for better KiCad library contribution (Git + KiCad)], KiCad.info Forums, May 2018</ref> |
||
To keep your fork current with the upstream repository:<ref name="howto"/> |
|||
<syntaxhighlight lang="linux-config"> |
|||
$ git merge upstream/master |
|||
</syntaxhighlight> |
|||
<!-- == See also == --> |
<!-- == See also == --> |
||
== Further reading == |
== Further reading == |
||
* ''Pro Git'' by Scott Chacon, Ben Straub Paperback, Apress, Nov. 2014, ISBN |
* ''Pro Git'' by Scott Chacon, Ben Straub Paperback, Apress, Nov. 2014, {{ISBN|9781484200773}} |
||
== References == |
== References == |
||
Line 133: | Line 159: | ||
== External links == |
== External links == |
||
=== KiCad === |
=== KiCad === |
||
* [http://kicad |
* [http://kicad.org/libraries/contribute/ Contributing to the KiCad libraries] |
||
* [https://github.com/KiCad KiCad EDA], GitHub repositories |
* [https://github.com/KiCad KiCad EDA], GitHub repositories |
||
* [https://github.com/kicad/kicad-library-utils KiCad/kicad-library-utils] |
* [https://github.com/kicad/kicad-library-utils KiCad/kicad-library-utils] |
||
* [http://kicad |
* [http://kicad.org/libraries/klc/ KiCad Library Convention] |
||
* [https://forum.kicad.info/t/library-management-in-kicad-version-5/14636 Library management in KiCad version 5], KiCad.info Forums |
* [https://forum.kicad.info/t/library-management-in-kicad-version-5/14636 Library management in KiCad version 5], KiCad.info Forums |
||
==== Tutorials ==== |
==== Tutorials ==== |
Latest revision as of 16:02, 20 October 2021
This description of the Git (and Python) workflow when contributing to the official KiCad libraries is intended as a simple walk-through how-to for users new to KiCad and Git but who have enough know-how to open a terminal and use the command line.
Contributing to KiCad
Instead of effort being wasted by any number of different designers recreating their own versions of symbols, footprints or 3d models of unknown quality, by contributing to the official libraries, the combined effort will help these to grow benefiting all KiCad users.[1]
The KLC
The KiCad Library Convention (KLC) is a set of requirements for contributing to the official KiCad libraries.[2]
The things that are really important still need to be hand checked. This is the main work that library maintainers do. For example the pin numbers, names and types still needs to be compared to the datasheet, for footprints a dimension check is also required.[1]
KiCad utilities
Before making a pull request use the KiCad utilities (Python scripts) to check whether the parts you are considering submitting are KLC compliant. They mainly check stuff that is only important for having a consistent library.[1]
Travis CI
On GitHub Travis CI checks KLC compliance of footprint files and symbol libraries.
Usage
See the README.md file. Run these in a terminal window using Python
Use pcb/check_kicad_mod.py to check KLC compliance of footprint files.
Use schlib/checklib.py to check KLC compliance of schematic symbol libraries.
GitHub (out of date, now hosted at GitLab)
GitHub simply hosts a Git server and provides a nice web interface.[3] The official KiCad libraries are hosted on GitHub.
One time SSH key setup
- If you don't have one already, create a GitHub account.
- On Windows install Git for Windows
- Generate a new SSH key and add it to the ssh-agent.
- Add the SSH key to your GitHub account.
Create a fork (e.g. footprints)
At https://github.com/KiCad/kicad-footprints click Fork at the top right, to fork your own copy of KiCad/kicad-footprints to your GitHub account.[4]
Note that https://github.com/KiCad/kicad-footprints is referred to as "upstream" and your fork https://github.com/YOUR-USERNAME/kicad-footprints as "origin".[5]
Git Bash
To go to your home directory, enter with no other text
cd
To list the files and folders in your current directory, enter
ls
To go into one of your listed directories, enter
cd your_listed_directory
To go up one directory, enter
cd ..
Git
Git is an open source distributed version control system (VCS) and is available for multiple OS. It is available for free.[6][7][8]
The command line is the only place you can run all Git commands, most of the GUIs implement only a partial subset of Git functionality for simplicity. If you know how to run the command-line version, you can probably also figure out how to run the GUI version, while the opposite is not necessarily true.[9]
Initial setup
The first thing to do is to set your user name and email address, every Git commit will use this information. Use the git config command with the --global option this only needs to be done once:[10][11]
To setup the user name
git config --global user.name "John Smith"
To setup the user email address
git config --global user.email john@example.com
To check the user name
git config user.name
To check the user email address
git config user.email
Usage (e.g. for footprints)
For help on common Git commands, enter:
git --help
For the manual page on a particular command, (e.g. add) enter:
git --help add
To have the files in your fork on your computer, create a clone of your fork locally on your computer with:
git clone https://github.com/YOUR-USERNAME/kicad-footprints
The commands below are done in the folder of your working copy of the fork (# marks a comment).
To update:
git pull
Add the official KiCad repo as another remote. This takes care of keeping all branches up-to-date between your downstream repository or fork ("origin") and the KiCad repo ("upstream"). This only needs to be done once:[10][12]
git remote add upstream https://github.com/KiCad/kicad-footprints.git
Make a separate pull request (PR) for each separate library, (e.g. Button_Switch_THT.pretty vs. Potentiometer_THT.pretty). To do this you need to have one branch per contribution:
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
Make your changes then:
git add --all # or git add list_of_files
git commit -m "descriptive_commit_message"
git push # push your changes online
Go to https://github.com/YOUR-USERNAME/kicad-footprints and click the "Compare & pull request" button to do the PR. Complete the form and click "Create pull request".
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 # without -b switch
Do your changes:
git add --all # or again git add file_list
git commit -m "descriptive_commit_message"
git push # push your fixes to GitHub (will automatically appear in the pull request)
To keep your fork current with the upstream repository:[12]
$ git merge upstream/master
Further reading
- Pro Git by Scott Chacon, Ben Straub Paperback, Apress, Nov. 2014, ISBN 9781484200773
References
- ^ a b c Contributing Parts - Selection, KiCad.info Forums, Sep 2018
- ^ KiCad Library Convention, v3.0.17
- ^ a b Git and the libraries for newbies, KiCad.info Forums, Feb 2019
- ^ a b Fork a repo, GitHub Help
- ^ What is the difference between origin and upstream on GitHub?, Stack Overflow
- ^ Git homepage
- ^ Version Control Software in 2014: What are Your Options?, Shaumik Daityari, 22 April 2014
- ^ PCB version control and notes, EEVblog forum, May 2015
- ^ Getting Started - The Command Line, Pro Git by Scott Chacon and Ben Straub
- ^ a b Setting up a repository, atlassian.com
- ^ Getting Started - First-Time Git Setup, git-scm.com
- ^ a b How to keep a downstream git repository current with upstream repository changes
- ^ Workflow for better KiCad library contribution (Git + KiCad), KiCad.info Forums, May 2018
External links
KiCad
- Contributing to the KiCad libraries
- KiCad EDA, GitHub repositories
- KiCad/kicad-library-utils
- KiCad Library Convention
- Library management in KiCad version 5, KiCad.info Forums
Tutorials
- Tutorial: How to make a symbol by Rene Poschl, KiCad.info Forums
- Tutorial: How to make a footprint (From scratch)? by Rene Poschl, KiCad.info Forums
Python
- Python, downloads
Git
Tutorials
- gittutorial, a tutorial introduction to Git
- Getting Git Right, Atlassian.com
Github
Tutorials
- GitHub Guides
- Introduction to Git with Scott Chacon of GitHub, a good explanation what Git is and how the basics work