Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
86 lines (67 loc) · 3.29 KB

CONTRIBUTING.md

File metadata and controls

86 lines (67 loc) · 3.29 KB

Contributing to Keychron Hardware Design

Thank you for contributing to Keychron's source-available hardware project! Whether you're fixing a tolerance, adding an ISO plate variant, or improving documentation, every contribution helps.

Important: This project is source-available. Original compatible accessories and add-ons are not subject to the commercial-use restriction in this license. By submitting a contribution, you agree that your contribution will be licensed under the same Keychron Source-Available License.

Types of Contributions

Bug Fixes / Corrections

  • Dimensional errors in STEP models
  • Incorrect screw hole positions or sizes
  • Plate cutout misalignment for specific switch types
  • Broken or corrupted files

New Content

  • ISO layout plate variants (currently missing)
  • Alternative plate materials (FR4, POM, polycarbonate)
  • Community case mods and accessories
  • 3D printing profiles and slicing presets
  • Additional keycap profile models

Documentation

  • Better file-format guides
  • Improved 3D printing instructions
  • Compatibility notes for specific CAD software

File Standards

Naming Convention

Recommended naming for new and updated files:

{Model}-{Variant}-{Component}-{Date}.{ext}

Many official files in this repository already follow this pattern, for example:

  • Q1-Top-Case.stp
  • K8-Max-US-Aluminum-Plate-20240924.dwg
  • V2-Max-US-Full-Model-20240812.stp
  • Stabilizer-6.25u.stp

Some existing official files use older naming styles, including underscores, lowercase prefixes, or 8k directory casing. Those legacy names may remain in place for historical compatibility, but new contributions should not copy those exceptions.

For community contributions and new official uploads, use Title-Case with hyphens, matching the model prefix:

  • Q1-ISO-Plate.dxf
  • K8-Max-POM-Plate.stp
  • Q5-FR4-Plate.dxf

Formats

  • 3D models: STEP (.stp) preferred. IGES (.iges) accepted.
  • 2D drawings: DXF (.dxf) or DWG (.dwg). Include a PDF export for reference.
  • Units: Millimeters (mm). Always.
  • Origin: Center of the PCB footprint, top surface.

Quality Checklist

Before submitting:

  • File opens without errors in FreeCAD or Fusion 360
  • Dimensions are in millimeters
  • New or renamed files use the recommended hyphenated Title-Case convention above
  • Model is watertight (for 3D-printable components)
  • No proprietary software lock-in (no .f3d-only submissions)

How to Submit

  1. Fork this repository
  2. Create a branch: git checkout -b fix/q1-plate-tolerance
  3. Add/modify files following the standards above
  4. Commit with a clear message: 
    fix(q1): correct plate cutout width for Cherry MX
add(q5): ISO plate variant
docs: add FreeCAD import guide
  5. Push and open a Pull Request
  6. Include a screenshot or dimension comparison in the PR description

Large Files

This repo uses Git LFS for binary CAD files. Make sure you have it installed:

git lfs install

The repository's .gitattributes file tracks the main CAD and document artifacts through LFS, including .stp, .step, .dwg, .dxf, .pdf, and .zip files.

Code of Conduct

All contributors must follow our Code of Conduct. Be respectful, constructive, and welcoming.