journal/stockcropper/SC-SOPS.md

Revision Date, Approved By

Revision Date	Approved By
07OCT2025	TJH

Rules are for the obedience of fools and the guidance of wise men.
- Douglas Bader

Often documents like these are very formal and militaristic. We ought to adhere to this document. However, we will not let it hamstring us. If there are things that it doesn't allow us to do, and we need to do them, we will revise this document wisely. We will not simply deviate from this document without addressing the problem with the process that led us to the deviation. It's OK to do things that deviate from this document for a while and see how they go. It's not OK to put anything into production or push to main without first discussing those changes and incorporating them into this document.

Component Types and Numbering

Components are given unique numbers. Why numbers? Numbers are cheap, succinct, clean, and consistent. The descriptions of parts may change over time, but the number stays the same.

Parts (SC-xxxx)

Parts are individual items that aren't meant to be broken down further. Parts may be assembled (or even permanently assembled). This includes both custom and off the shelf components.

Parts are numbered: SC-xxxx

Parts have these files associated with them:

File Type	Extension	Notes
SOLIDWORKS Model	.sldprt	Master CAD file - for 3D geometry
SOLIDWORKS Drawing	.slddrw	Master Drawing file - contains all other information such as material, tolerances, etc.
STEP Model	.step	(exported, do not edit)
Drawing	.pdf	(exported, do not edit)
Sheetmetal File (Optional)	.dxf	(exported, do not edit)
STL Model (Optional)	.stl	(exported, do not edit)

Assemblies (SC-Axxx)

Assemblies are a collection of parts that are meant to be installed together.

Assemblies are numbered: SC-Axxx

Assemblies have these files associated with them:

File Type	Extension	Notes
SOLIDWORKS Model	.sldasm	Master CAD file - for 3D geometry
SOLIDWORKS Drawing	.slddrw	Master Drawing file - contains all other information such as material, tolerances, etc.
STEP Model	.step	(exported, do not edit)
Drawing	.pdf	(exported, do not edit)

Harnesses (SC-Hxxx)

Harnesses are wires, cables, and electrical connectors that are assembled together.

Harnesses are numbered: SC-Hxxx

Harnesses generally have these files associated with them:

File Type	Extension	Notes
SOLIDWORKS Model (optional)	.sldasm	Usually a geometric representation. Not at all for production purposes.
SOLIDWORKS Drawing (optional)	.slddrw
WireViz Model	.yml	A harness described in markup language
STEP Model (optional)	.step	(exported, do not edit)
Drawing	.pdf	(exported, do not edit)

%% TODO: figure this one out a lot more %%

Boards (SC-Bxxx)

Boards are assemblies of electrical components that have been soldered together. They have a single custom PCB and several individual subcomponents that may have designators such as C1, J_FTDI1.

Board design is in the form of a KiCAD project (which contains multiple files).

Boards are numbered: SC-Bxxx

%% TODO: put more detail on the particular files... especially BOMs %%

Weldments (SC-Wxxx)

Weldments are a collection of parts that are welded together. Weldments consist of several parts.

Weldments are numbered: SC-Wxxx

Weldments have these files associated with them:

File Type	Extension	Notes
SOLIDWORKS Model	.sldasm	Master CAD file - for 3D geometry
SOLIDWORKS Drawing	.slddrw	Master Drawing file - contains all other information such as material, tolerances, etc.
STEP Model	.step	(exported, do not edit)
Drawing	.pdf	(exported, do not edit)

Programs (SC-Pxxx)

Programs are software that runs on hardware. They are numbered, but may only be numbered on a folder basis. Any built binaries are definitely numbered. This is pretty easy to deal with.

Revisions and Releasing Files

The above are "base" filenames. These are the filenames one would use for the active project. However, at certain points, we will want to make releases for these files. Files associated with a particular release should have suffixes -Vx. Versions are cheap. Both the "source" files (such as SOLIDWORKS models and drawings) and "compiled" files (such as STEP models, PDFs) should be included.

For example, when you are done with a part SC-0001 and wish to create a version V2, you should create these files (assuming SC-0001 was drawn in SOLIDWORKS):

• SC-0001-V1.sldprt
• SC-0001-V1.slddrw
• SC-0001-V1.step
• SC-0001-V1.pdf

All of these files should then be put in the released folder.

You should also then update the SC-PARTNUMBERS.ods spreadsheet.

One may quickly notice that these are, thusly, "dependencies". Say that SC-A001 contains SC-0002 and SC-0003. If one updates SC-0002, SC-A001 should be revision-bumped.

We will keep this a "should" for now and create tools that will help identify when this goes wrong.

SOLIDWORKS Part Files

Everything but the .stl export is handled by the export tool. Make sure that you have all assemblies / parts referencing the part closed before running the export tool.

• Save the .sldprt.
• Save the .slddrw.
• Save the .sldprt to a .step file, version AP242.
• Save the .slddrw to a .pdf file.
• If the part is sheet metal/plastic, save the flat pattern (including any bend lines) to a .dxf.
• If the part is to be printed, save the model to a .stl.
• Update the version in SC-PARTNUMBERS.ods and ensure the component description matches the drawing.
• Move old version files to the archive folder, if applicable.

SOLIDWORKS Assembly Files

Make sure that you have all assemblies / parts referencing the part closed before running the export tool.

• Save the .sldasm.
• Save the .slddrw.
• Save the .sldasm to a .step file, version AP242.
• Save the .slddrw to a .pdf file.
• Update the version in SC-PARTNUMBERS.ods and ensure the component description matches the drawing.
• Move old version files to the archive folder, if applicable.

KiCAD Files

Everything but the .stl export is handled by the export tool. Make sure that you have all assemblies / parts referencing the part closed before running the export tool.

• Archive the entire project to a .zip file.
• Update the version in SC-PARTNUMBERS.ods and ensure the component description matches the drawing.
• Move old version files to the archive folder, if applicable.

Branching - Data Control

One may notice then that revision control can be accomplished entirely without a server. So how can multiple people work together and backups be made? Simple: use git. We'll also have a git server set up, but this isn't necessary. Git is meant to be a distributed system. We will use git as it was intended to be used in this regard, even though we are using git to manage (mostly) binary files.

The main branch is where all released files should live. Everything in main should be released; the 'living' files should match the released files (i.e. SC-0001.sldprt matches SC-0001-V1.sldprt... if V1 is the latest version.)

That doesn't mean we only use git when everything is done. Use branches other than main to do development work on.

Future Development - Tools

We want to do these things:

• Get all the latest versions of every part
• See if assemblies (incl. weldments) include out-of-date parts
  • See if parts are referencing out of date parts?