-
Notifications
You must be signed in to change notification settings - Fork 369
Contributing
If you would like to contribute to the project, awesome! Here's how to get started:
Aside from cloning the repository, there's a few things to install. We've chosen software that works totally cross-platform, so you should be able to contribute regardless of your OS:
-
KiCAD
- We use KiCAD for all of our PCB designs. Install the latest stable release, not the nightly build.
-
FreeCAD
- FreeCAD is our mechanical CAD package. It's scriptability and offline support make it ideal for managing with git and automating tasks. Make sure to install the latest stable release.
-
Visual Studio Code
- VS Code is an excellent IDE that we use for firmware development. Make sure to install the latest stable release.
-
PlatformIO VS Code Plugin
- PlatformIO is a build system and debugger that installs on top of VS Code. This is what we use for compiling, debugging, and uploading firmware to the feeders and the motherboard.
-
Git LFS
- We use Git LFS to make sure we don't have merge conflicts with KiCAD and FreeCAD files. Install it with the link and run
git lfs install
to set it up with your account.
- We use Git LFS to make sure we don't have merge conflicts with KiCAD and FreeCAD files. Install it with the link and run
-
Discord
- We use Discord to discuss changes and coordinate work. You can join the server using [this link].(https://discordapp.com/invite/TCwy6De).
Once you have the relevant software installed, make a fork of the main Index repo. Then, clone the fork to your computer.
git clone [email protected]:YOUR_USERNAME/index.git
The Index Github repo operates under a feature-branch methodology. This means that work for an enhancement or bug fix happens in a separate branch made specifically for that change (or series of changes). Individual contributors make changes in their forks, and merge them into the main repo's feature branch. Once the feature branch is done, it's then merged into master once it's complete. After the merge, the resultant commit is tagged with a new release number.
When working with text, git does an excellent job handling merging two separate versions of a file. However, we are using git to track CAD files where a merge process is much less simple. To solve this issue, we use Git LFS (Large File Storage).
Git LFS is a tool for tracking and managing large binary files using git. We use it mainly for the lock
feature it provides. Merging KiCAD and FreeCAD files is technically possible given that they're stored in plaintext, but completely infeasible. To prevent the need to merge them, we instead have one person lock the source file before starting editing and until after merging so no conflicts arise.
The ability to lock files is unfortunately only available to accounts that have been given Collaborator credentials. Instead of locking files yourself, have a Collaborator lock them in your stead. If you haven't already, join the Discord Server and ask about getting files locked in the #index-dev channel.
Even though you won't be locking files yourself, you still need Git LFS installed to view the files. Instead of storing the binary directly in the repo, Git LFS just stores a hash of the file in the repo, and puts the binary in a separate server. If you don't have LFS installed, some files might not be able to open properly. If you have it installed, Git LFS will take care of everything behind the scenes and your normal git commands will work as expected.
The only files that we lock using git lfs
are .FStd
files (for FreeCAD), plus .sch
and .kicad_pcb
files for KiCAD.
It's important to note that if you don't have the files locked before you start working, we might not be able to merge your work. Make sure to get any KiCAD or FreeCAD files locked before starting work.
Now that you've cloned your fork to your machine and have some files locked, it's time to get going! Make sure that your fork is up to date with the main repo (you can see how to do that here). Checkout the relevant feature branch in your fork and go for it! Commit frequently with descriptive commit messages. Once you're finished, push up to your fork and file a Pull Request. Be sure to tag any relevant Issues that your PR is relevant to or solves.
Versioning for the Index and all of its parts is important for tracking which part versions are included in which build. Every component in the Index has a unique part number. All part numbers refer to a single component in the machine. A list of every part number in the project is in parts.csv
in the root directory of this repo. Refer to this before adding a part number to ensure there are no repeats. Product-specific parts should live within the product's dedicated folder. Parts that can be shared (like hardware, connectors, etc) are stored in the lib
folder. The format for part numbers are as follows:
PRT-0001-00
where:
-
PRT
is a capital, three letter part type designator. This says what kind of part it is. -
0001
is a part ID unique within the part type designator. For example, IJM-0001-00 and FDM-0001-00 are valid, unique part numbers. -
00
is the revision. Any time there is a design change, no matter how small, the revision number needs to be incremented. This only counts for actual changes in the design. Assembly instructions or vendor changes should not cause an uprev.
Below is a list of valid part type designators:
- OTS - Off The Shelf. Can be purchased directly from a vendor.
- FDM - Fused Deposition Modeling. A part printed on an FDM machine.
- PCB - Printed Circuit Board. Just references the actual board itself, not the components that populate it (which are considered OTS).
The following are standards that we adopt across the project. They help make the Index easier to build, reduce part count, and reduce cost.
Mechanical
- All parts are modeled separately in their own FCDStd file, and then put into a final assembly file.
- Stick to Metric unless absolutely necessary to do otherwise (eg. off the shelf part only has 1/4-20 threading available)
- Use M3 and M5 hardware whenever possible. We use these across the build and keeping them standard reduces part count.
- Favor captive nuts as opposed to heat set inserts. They are easier to install, much cheaper, and much less likely to pull out.
- All custom parts should heavily consider printability in FDM. Try to allow parts to fit within a 150mm X 150mm X 150mm build volume. Design your parts around printing support-free.
Electrical
- 2-layer boards are standard. 4-layer boards are used if it truly is required for routing, power delivery, RF, or other specific reasons. Spending a bit more time to route a board is worth the saved cost for all the folks ordering them.
- Choose an SMD part instead of a THT part. This makes it easier to fabricate the board using a pick and place.
- All passives should be 0805, unless it is absolutely necessary to deviate. This is to aid in reliability of being picked and placed, but also so that folks can easily hand solder if they wish.
- For parts such as connectors, jacks, and other large parts, use a hybrid footprint. This means using a footprint that allows for both a THT and an SMD part to occupy the same space.
- If possible, use components that are already in the BOM to reduce unique part count.
- Ensure that any components added to the BOM have at least two sources that ship globally with large stock (Digikey, Mouser, LCSC are good ones to check).
- Hop in the Discord and chat about the changes you'd like to make. Be sure to include the issue number that your change will address. (No issue yet? Make one, and mention it when discussing in Discord.)
- Have one of the Collaborators lock the files you need to edit in your stead.
- Ensure that your fork is up to date with the main repo.
- Checkout the branch you'll be making edits to.
- Make changes. Commit often.
- Push your changes to your fork on Github.
- File a Pull Request into the main repo's relevant feature branch.
- Once merged, notify the Collaborator that locked the files you needed that the lock can be removed.
- Close any issues that have been fixed by the merge.
All feature requests, bugs, and planned enhancements are logged as Issues in Github. There are multiple different tags that we use to keep track of them. There are four types of tags:
Product:
These indicate which product the issue is relevant to. Either index
or feeder
Type:
These indicate if it's fixing an active problem, or an improvement. Either bug
or enhancement
Discipline:
These indicate what skillset is required to complete the task. All relevant from the following should be chosen: cad
, code
, pcb
, or documentation
Misc:
These indicate an extra bit of info that can be helpful to filter by. marlin
and openpnp
are included because sorting by these tags can help bundle changes into the same PR for less interference with an existing project. help wanted
and good first issue
are helpful for folks looking to help contribute. requires validation
indicates a bit of prototype and testing work needs to be done before work on the issue can begin. wontfix
is for issues we've decided not to pursue.