Public:GitHub/PCB

KiCad conveniently uses human readable and therefore version-able text based file types. Therefore all of our PCBs are stored at IlliniSolarCar/PCB on GitHub. This version-ability is a major part of the KiCad design philosophy so the use of GitHub for PCBs is expected to continue for a long time.

Note: Using git for PCBs started in 2017/2018 when we switched to KiCad. Before that we used DipTrace which is not git compatible. You will find many of the PCBs on GitHub and can open them with DipTrace, or you can view PDFs for most major boards on Box.

Workflow

Branch Structure

This diagram shows a simplified branch structure of the PCB and Hardware Libraries repos and how they interact

Doing the actual KiCad work of designing a PCB is not a collaborative work the same way code can be. Multiple people cannot edit the same boards at the same time - it will result in unresolvable conflicts. Therefore, git is just a versioning tool and the PCB repo is mostly linear. Each board will have its own development branch which is created for that board and deleted when the board is done. There are no long standing development branches. Sometimes, multiple very simple similar boards could be on one branch, but in most cases you don't want to do this so that they can individually go through the review process. If needed (there are new parts) you will also have a corresponding branch on the IlliniSolarCar/isc-hw-libs repo.

Starting a Project

1. Create and checkout a branch for your project in the PCB (and Libraries if needed) repository using git checkout -b <branch>. Make sure you are on master while you do this!
2. Copy the latest template from the Dev folder
3. Rename your file structure to follow the Storage Conventions - you will have to rename the folder and each project file manually. Do not rename the .kicad_wks file or you'll be sorry the nice logo and other settings disappear
4. Make an initial commit to the Libraries and PCB repositories (in that order) as below
   • For the first push use git push --set-upstream origin <branch> to create the branch on GitHub

Making Changes

See PCB Design for what happens in-between, while you are creating your board!

The following describes the process for editing the PCB repo without changing libraries:

1. Edit the PCB files
2. Stage the changes for the next commit using git add <files> To stage all changes use git add or git add -a
3. Commit the changes using git commit -m "<commit message>"Include a useful message to help people reading through the history see what was done.
4. Push the changes to GitHub using git push.

Editing libraries requires a different process, but it's the same whether editing just the Libraries or the Libraries and the PCB files.

1. Edit the libraries and PCB files
2. Ensure your working directory is the Libraries directory. This is to ensure changes are being made to the library repository, instead of the PCB repository.
3. Stage( git add ), commit( git commit ), and push( git push ) the Library changes as described above.
4. Change your working directory to the PCB repo
5. Stage your changes. Make sure Libraries is included or the changes in the libraries will not update on GitHub.
6. Commit and push as above.

If you do not do this, git will not have the right libraries associated with your PCB branch. When others open it and update their submodule they won't be able to see the components you added to libraries.

Whenever changes are made on another computer, you need to get the changes with the following process:

1. Pull the changes to the PCB files with git pull --recurse-submodules
2. If you forgot to add --recurse-submodules, use git submodule update--init

Pull Requests

When you have your board ready for review you will open a Pull Request (PR) to the master branch. If applicable, the Libraries branch should also have a PR open by this point - that mus be merged first. (Note: your PCB branch must reference the master Libraries submodule before merging).

Once your PR is open your board needs to be reviewed. Expect your board to go through many rounds of review and be ready to make the needed changes. Especially on the PCB layout the changes you make can introduce new problems. It is not uncommon for the review process to result in a lot of work to do in a short time if you don't give yourself adequate time before the board run.

Once your board has been approved by 2 reviewers and passes all checks it will be allowed to be merged to master. You should Squash and Merge your PRs on the PCB repo. Intermediate versions of partially complete boards are not very useful for us to keep.

Boards will only be manufactured if they are on master! Some boards on master may not have been made (usually requirements changed before they were made, especially in early ISC days), but generally master is the board that have been made and other branches are in progress boards.

Github Checks / Actions

Another perk of human readable KiCad files is that we can write scripts to parse them to hep with our review process!

Labeler

This is an action set-up with the Github Provided labeler action. It just labels the PR and does not fail. Currently it isn't set-up to do much, but can easily be improved by editing the label.yml file.

Initial Setup

In order to get the PCBs onto your computer, use git clone --recursive <repo URL> <optional custom folder name>. The --recursive option looks for submodules (such as Libraries) in the repo and clones them into the correct directory. If this option was omitted during the initial clone, run the command git submodule update --init to find any un-cloned submodules and clone them.

Once you have the PCBs cloned onto your computer, follow the instructions to set up KiCad. Once this is done, you should be able to open the latest manufactured PCBs.

To open a PCB that is being designed (i.e. not on master), checkout the branch using git checkout <branch> --recurse-submodules. If you forget the submodule option, use git submodule update to get the correct libraries. If you do not have the correct libraries you will only be able to see the components that were in the submodule version linked from the master branch.

If you cannot get components from our libraries to work for an older PCB, it may have been designed before the big libraries update that came with Kicad v5. See info on the KiCad page about upgrading projects.

KiCad Files and Git

KiCad has a lot of files of different file types it generates. Unlike other programs, that might put these all in temp, KiCad puts many of them in the project repo. For the target audience of KiCad, that is Engineers, this makes sense as it gives us the power to use these files as we may need them.

KiCad has a bit of a habit of adding more of these, so this page might be out of date. You can see the up to date list for the current release version on the KiCad Website. Luckily, this is supposedly addressed in KiCad v6.

KiCad files are intentionally human readable and compatible with version control, allowing better collaboration than other tools. We take significant advantage of this in our workflow, but we don't need all your files on git - it can get messy with how many KiCad has. Read below for which files to include or not include. This should mostly be handled by the .gitignore if you don't override it.

Project File Types

File Name / Extensions	Type	Include on Git	Description
projectName.pro	KiCad Project Meta File	REQUIRED	This file contains information about the KiCad project. There can only be one project file per project! (If you see others associated with your hierarchical schematics, get rid of them and don't open your schematic files straight from your file browser.)
projectName.sch	KiCad Schemaatic File	REQUIRED	This is the top-level schematic for the project. You can add additional schematic files to your project and include them as heirarchical schematics, or "schematics within a schematic"
projectName.kicad_pcb	KiCad PCB File	REQUIRED	This is the physical layout of your circuit board. There can only be one PCB per project!
projectName_subSection.sch	KiCad Schematic File	Optional	It is normal to have more than one schematic file. Since each schematic file is the size of one page of paper when printed, it is common to have multiple-page schematics for larger projects
sym-lib-table	KiCad Library Database	REQUIRED	This tells KiCad what symbol libraries your project uses. If it doesn't exist, all your components will be '?'.
fp-lib-table	KiCad Library Database	REQUIRED	This tells KiCad what footprint libraries your project uses. If it doesn't exist, you won't be able to add new footprints or update them from library changes.
Title_Block.kicad_wks	KiCad Page Layout Description	REQUIRED	This tells KiCad how to make your pages look, especially the title block in the corner. Helps us keep a consistent ISC look to projects
projectName_specs.md	Illini Solar Car PCB Specs Document	REQUIRED	The document outlining the specifications and requirementsof your board. Should be complete before you start and also updated as you go. This is needed for project management, reviewing boards, and for people in the future to understand boards
symbols/	Folder	Optional	This folder contains any local symbol libraries you create. You can put stuff here that you don't want to commit to the main libraries, for example, a board specific symbol. See the Symbols Libraries section below for more information on what goes in here. These are uncommon
footprints.pretty/	Folder	Optional	This folder contains any local component footprints you create. You can put stuff here that you don't want to commit to the main libraries. See the Footprint Libraries section for more information on what goes in here. These are more common for board specific physical components.
models.3dshapes/	Folder	Optional	This folder contains 3D CAD models of components. See the 3D Model Libraries section for more information on what goes in here
bom.ini	BOM Settings File	Optional	This file is generated by the KiCad BOM generator plugin if it can't find a settings file. It contains information on how the BOM plugin parses the component list to generate the BOM
schematicName.bak	KiCad Schematic Backup File	NEVER	This file contains a backup of your schematic when it's saved. If you really mess something up and the previous git commit is not up-to-date at all (in this case, shame on you!), then you can change the name of this file to have a .sch ending and open it in KiCad
projectName.kicad_pcb-bak	KiCad PCB Backup File	NEVER	This file is a back-up of your PCB when it is saved. If you really mess something up and the previous git commit is not up-to-date at all (in this case, shame on you!), then you can change the name of this file to have a .pcb ending and open it in KiCad
_saved_anyName.sch	Autosave	NEVER	This file is an autosave file from KiCAD to restore from crashes. YIf you have one of these, you should fix things that may have broken due to the crash. We don't need them on git.
projectName-cache.lib	KiCad Library File, Automatic	NEVER	This file will be generated automatically by KiCad to store a local copy of schematic symbols. This lets you view the schematic even if the main libraries are unavailable (but should not replace using them!), and it protect you if symbols in a library change

KiCad has a lot more temporary type files not listed here, you shouldn't have any issue with those - they typically get cleaned up by KiCad

Manufacturing Files

File Name / Extensions	Type	Include on Git	Description
projectName_gerbers.zip	Zip File of Manufacturing Files	REQUIRED	The zip file of all manufacturing files (.gbr and .drl) used to make this board.
projectName-LayerName.gbr	Gerber File for a specific layer of the board	NEVER	Gerber File format for PCB Layers. Not version-able, and redundant after the zip file. Do not put on git.
projectName.drl	Drill File for the PCB	NEVER	File for specifying where the board needs to be drilled through (such as for mounting holes). Redundant after the zip file, Do not put on git.

Library Files

See GitHub/isc-hw-libs. Sometimes you may have project specific Libraries which will be on the PCB repo. These should follow the same guidelines as they would on the Libraries repo.

Credit to Byron Hopps for the content pre- 10-07-18