Public:GitHub/PCB

IlliniSolarCar/PCB Active
ReadMe
Issues Pull Requests Releases
Content:	All Printed Circuit Boards Designed in KiCad
Access:	Private
License:	All Rights Reserved to ISC
Branching Strategy:	Topic/Project Branches
Maintained By:	Electrical Group
Actions & Checks:	Master Reviews Required Auto labeling
View All ISC Repos GitHub/ARGO-FW GitHub/b-fw GitHub/CAN GitHub/FW GitHub/isc-hw-libs GitHub/mbed GitHub/PCB GitHub/Telemetry

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

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 file 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, a few very simple similar boards could be on one branch (such as Lights), but in most cases you don't want to do this because we want to review each board by itself. If you need to add or change components in our component libraries, you'll 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 repository using git checkout -b <branch>. Make sure you are on the latest version of the master branch while you do this!
2. Copy the latest template from the ~/your path/PCB/Dev/Template_v0.0 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.

1. Edit the libraries
2. Ensure your working directory is the ~/your path/isc-hw-libs directory. This is to ensure changes are being made to the GitHub/isc-hw-libs, instead of the PCB repository.
3. Stage( git add ), commit( git commit ), and push( git push ) the Library changes as described above.
4. Commit and push as above.

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

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.

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. We use Squash because we don't need to keep the entire design process of each board in the history, just the finished board.

Boards will only be manufactured if they are on master! Some boards on master may not have been manufactured (from early ISC days), but generally master contains the boards 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 help 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.

Title Block Check

This check verifies the Title Blocks in your schematics and PCBs meet the requirements (it only checks the files you change on the PR). See the Schematic Conventions for Title Block information. Note that our configuration doesn't guarantee that you filled out everything correctly - but mostly just that you filled it out. You can view the regex it checks for in the config file

Initial Setup

In order to get the PCBs onto your computer, use git clone <repo URL> <optional custom folder name>.

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>.

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 Schematic File	REQUIRED	This is the top-level schematic for the project. You can add additional schematic files to your project and include them as hierarchical 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 across projects.
projectName_specs.md	Illini Solar Car PCB Specs Document	REQUIRED	The document outlining the specifications and requirements of 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. If 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 protects 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.