| You are not Logged In! |
Difference between revisions of "Public:GitHub/PCB"
Jump to navigation
Jump to search
(Checks info) |
|||
| (7 intermediate revisions by 4 users not shown) | |||
| Line 9: | Line 9: | ||
=== Branch Structure === | === Branch Structure === | ||
| − | [[File:GitHub Hardware Branches Chart.png|thumb| | + | [[File:GitHub Hardware Branches Chart.png|thumb|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, | + | 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 Electronics|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 {{GithubRepo|org=IlliniSolarCar|repo=isc-hw-libs}} repo. |
=== Starting a Project === | === Starting a Project === | ||
| − | # Create and checkout a branch for your project in the PCB | + | # Create and checkout a branch for your project in the PCB repository using <code>git checkout -b <branch></code>. Make sure you are on the latest version of the master branch while you do this! |
| − | # Copy the latest template from the <code>Dev</code> folder | + | # Copy the latest template from the <code>~/your path/PCB/Dev/Template_v0.0</code> folder |
# Rename your file structure to follow the [[Standards|Storage Conventions]] - you will have to rename the folder and each project file manually. ''Do not'' rename the <code>.kicad_wks</code> file or you'll be sorry the nice logo and other settings disappear | # Rename your file structure to follow the [[Standards|Storage Conventions]] - you will have to rename the folder and each project file manually. ''Do not'' rename the <code>.kicad_wks</code> file or you'll be sorry the nice logo and other settings disappear | ||
# Make an initial commit to the Libraries and PCB repositories (in that order) as below | # Make an initial commit to the Libraries and PCB repositories (in that order) as below | ||
| Line 27: | Line 27: | ||
# Commit the changes using <code>git commit -m "<commit message>"</code>Include a useful message to help people reading through the history see what was done. | # Commit the changes using <code>git commit -m "<commit message>"</code>Include a useful message to help people reading through the history see what was done. | ||
# Push the changes to GitHub using <code>git push</code>. | # Push the changes to GitHub using <code>git push</code>. | ||
| − | Editing libraries requires a different process | + | Editing libraries requires a different process. |
| − | # Edit the libraries | + | # Edit the libraries |
| − | # Ensure your working directory is the <code> | + | # Ensure your working directory is the <code>~/your path/isc-hw-libs</code> directory. This is to ensure changes are being made to the [[GitHub/isc-hw-libs]], instead of the PCB repository. |
# Stage( <code>git add</code> ), commit( <code>git commit</code> ), and push( <code>git push</code> ) the Library changes as described above. | # Stage( <code>git add</code> ), commit( <code>git commit</code> ), and push( <code>git push</code> ) the Library changes as described above. | ||
| − | |||
| − | |||
# Commit and push as above. | # Commit and push as above. | ||
| − | |||
Whenever changes are made on another computer, you need to get the changes with the following process: | Whenever changes are made on another computer, you need to get the changes with the following process: | ||
| − | # Pull the changes to the PCB files with <code>git pull | + | # Pull the changes to the PCB files with <code>git pull</code> |
| − | |||
=== Pull Requests === | === 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 | + | 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. {{Highlight|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 | + | Once your PR is open your board needs to be reviewed. {{Highlight|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 <u>2</u> reviewers and passes all checks it will be allowed to be merged to master. You should {{Highlight|Squash and Merge}} your PRs on the PCB repo. | + | Once your board has been approved by <u>2</u> reviewers and passes all checks it will be allowed to be merged to master. You should {{Highlight|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 | + | '''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 === | === Github Checks / Actions === | ||
| − | Another perk of human readable KiCad files is that we can write scripts to parse them to | + | Another perk of human-readable KiCad files is that we can write scripts to parse them to help with our review process! |
==== Labeler ==== | ==== Labeler ==== | ||
| − | This is an action set-up with the [https://github.com/actions/labeler Github Provided labeler] action. It just labels the PR and does not fail. Currently it isn't set | + | This is an action set-up with the [https://github.com/actions/labeler 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 [https://github.com/IlliniSolarCar/PCB/blob/master/.github/workflows/label.yml label.yml] file. |
| − | |||
| − | |||
| − | |||
==== Title Block Check ==== | ==== 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. | + | 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 [https://github.com/IlliniSolarCar/PCB/blob/master/.github/workflows/check-title-blocks.yml config file] |
== Initial Setup == | == Initial Setup == | ||
| − | In order to get the PCBs onto your computer, use <code>git clone | + | In order to get the PCBs onto your computer, use <code>git clone <repo URL> <optional custom folder name></code>. |
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. | 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 <code>git checkout <branch> | + | To open a PCB that is being designed (i.e. not on master), checkout the branch using <code>git checkout <branch></code>. |
| − | ''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 | + | ''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 Files and Git == | ||
| Line 75: | Line 68: | ||
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 [https://kicad-pcb.org/help/file-formats/ KiCad Website]. Luckily, this is supposedly addressed in [[KiCad v6]]. | 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 [https://kicad-pcb.org/help/file-formats/ 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 [https://github.com/IlliniSolarCar/PCB/blob/master/.gitignore .gitignore] if you don't override it. | + | 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 [https://github.com/IlliniSolarCar/PCB/blob/master/.gitignore .gitignore] if you don't override it. |
=== Project File Types === | === Project File Types === | ||
| Line 90: | Line 83: | ||
|- | |- | ||
|projectName.sch | |projectName.sch | ||
| − | |KiCad | + | |KiCad Schematic File |
|REQUIRED | |REQUIRED | ||
| − | |This is the top-level schematic for the project. You can add additional schematic files to your project and include them as | + | |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 | |projectName.kicad_pcb | ||
| Line 102: | Line 95: | ||
|KiCad Schematic File | |KiCad Schematic File | ||
|Optional | |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 | + | |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 | |sym-lib-table | ||
| Line 117: | Line 110: | ||
|KiCad Page Layout Description | |KiCad Page Layout Description | ||
|REQUIRED | |REQUIRED | ||
| − | |This tells KiCad how to make your pages look, especially the title block in the corner. Helps us keep a consistent ISC look | + | |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 | |projectName_specs.md | ||
|Illini Solar Car PCB Specs Document | |Illini Solar Car PCB Specs Document | ||
|REQUIRED | |REQUIRED | ||
| − | |The document outlining the specifications and | + | |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/ | |symbols/ | ||
|Folder | |Folder | ||
|Optional | |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 | + | |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/ | |footprints.pretty/ | ||
| Line 142: | Line 135: | ||
|BOM Settings File | |BOM Settings File | ||
|Optional | |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 | + | |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 | |schematicName.bak | ||
|KiCad Schematic Backup File | |KiCad Schematic Backup File | ||
|NEVER | |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 | + | |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 | |projectName.kicad_pcb-bak | ||
|KiCad PCB Backup File | |KiCad PCB Backup File | ||
|NEVER | |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 | + | |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 | |_saved_anyName.sch | ||
|Autosave | |Autosave | ||
|NEVER | |NEVER | ||
| − | |This file is an autosave file from | + | |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 | |projectName-cache.lib | ||
|KiCad Library File, Automatic | |KiCad Library File, Automatic | ||
|NEVER | |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 | + | |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 | + | 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 === | === Manufacturing Files === | ||
| Line 190: | Line 183: | ||
=== Library Files === | === 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. | + | 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. |
| − | |||
| − | |||
{{PCB Design Navbox|collapsed=true}} | {{PCB Design Navbox|collapsed=true}} | ||
Latest revision as of 14:30, 9 November 2023
 IlliniSolarCar/PCB
Active | |
|---|---|
| ReadMe | |
| 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: |
|
|
View All ISC Repos
| |
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
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
- 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! - Copy the latest template from the
~/your path/PCB/Dev/Template_v0.0folder - 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_wksfile or you'll be sorry the nice logo and other settings disappear - 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
- For the first push use
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:
- Edit the PCB files
- Stage the changes for the next commit using
git add <files>To stage all changes usegit addorgit add -a - Commit the changes using
git commit -m "<commit message>"Include a useful message to help people reading through the history see what was done. - Push the changes to GitHub using
git push.
Editing libraries requires a different process.
- Edit the libraries
- Ensure your working directory is the
~/your path/isc-hw-libsdirectory. This is to ensure changes are being made to the GitHub/isc-hw-libs, instead of the PCB repository. - Stage(
git add), commit(git commit), and push(git push) the Library changes as described above. - Commit and push as above.
Whenever changes are made on another computer, you need to get the changes with the following process:
- 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.
| ||||||||||||||||||||||||||||||||||||||||
