Skip to content

Contributing

Jump to bottom
Stephen Hawes edited this page Jun 17, 2021 · 26 revisions

If you would like to contribute to the project, awesome! Here's how to get started:

Getting Set Up

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.
  • Discord
    • We use Discord to discuss changes and coordinate work. You can join the server using this link.

Once you have the relevant software installed, make a fork of the main Index repo. Then, clone the fork to your computer.

git clone git@github.com:YOUR_USERNAME/index.git

Making a Contribution

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. A description of this git methodology can be found here.

Locking

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.

Making a Change

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

Part Numbers

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 that gets merged into the Master branch, 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).

Build Numbers

There are also version numbers for releases, called build numbers. There's a release every time a feature or bugfix branch is merged into master, and there's a new valid configuration of the machine. Releases are tagged using a version number in the style of semantic versioning, where, in part number vA.B.C:

  • A uprevs indicate a large change in the project that could be backwards-compatibility breaking, or major releases with lots of significant updates. (eg. switching from voltage dividers to 1-Wire EEPROMs for feeder slot IDs. This changes things in lots of areas of the project, and is backwards compatibility breaking.)
  • B uprevs indicate feature adds, large code reworks, CAD improvements, PCB revision releases, and other moderate changes. These are backwards compatible.
  • C uprevs indicate small bug fixes, typos, or other small changes.

Standards

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).
  • When a new feature branch is made for a new revision of a PCB, immediately commit and push a change to the board's silkscreen, incrementing the revision number, and appending "-BETA" to it. For example, if making a new branch for REV02 of the feeder PCB, make a new branch off of the Master branch titled "feeder-rev02" and update the silkscreen label from "REV01" to ""REV02-BETA". The "-BETA" indicates that this version of the board is not an official release, and could still have issues or be incomplete. Once BETA versions of the board have been ordered, tested, and validated, along with any code or CAD updates associated with the PCB uprev, a final commit on the "feeder-rev02" branch removes the "-BETA" from the silkscreen, and it should be deleted after merging into Master.

Full Workflow

  1. 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.)
  2. Have one of the Collaborators lock the files you need to edit in your stead.
  3. Ensure that your fork is up to date with the main repo.
  4. Checkout the branch you'll be making edits to.
  5. Make changes. Commit often.
  6. Push your changes to your fork on Github.
  7. File a Pull Request into the main repo's relevant feature branch.
  8. Once merged, notify the Collaborator that locked the files you needed that the lock can be removed.
  9. Close any issues that have been fixed by the merge.

Working With Issues

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.

Clone this wiki locally