Public Lab Wiki documentation



Contributing to Public Lab hardware

This is a revision from November 22, 2015 15:47. View all revisions
2 | 7 | | #12417

Rough Draft

This is a first attempt at a well-documented way for people to post suggested improvements to Public Lab tools, so that they may be integrated into a "base design" -- which will also be the version the Kits Initiative will produce and ship. Leave a comment on this post if you'd like to be involved -- this workflow is evolving!

Overview

For now, we're piloting this workflow with the Public Lab Spectrometer project, but leave a comment here if you'd like a project your involved in to follow it too.

Basically, we'd like:

  • it to be easy for anyone to post an upgrade
  • the maintainers (see below) to be responsible for responding to, and attempting to integrate upgrades
  • public dialogue about what design goals are, and what needs to happen for an upgrade to meet them
  • clear expectations and public dialogue about how, when and why new changes are incorporated

Project maintainers

Who decides if a change can be integrated?

Great question. Borrowing from the free software world we're proposing that each project will have a "maintainer" who's the point person for reviewing and merging updates, communicating, documentation, etc. That's not to say they'll be a monarch -- maintainers' main job will be communciating between contributors, supporting and sheparding new contributions, and above all transparency -- keeping the community up to date on the roadmap, development progress and active design discussions.

It'll also be their job to ensure that there's a broad base of contribution. If it's too hard to contribute, because the design files are too hard to find or read, or require expensive tools to edit, or because submissions are shouted down by an unfriendly and unhelpful gang of jargon-wielding technocrats, that's a problem! We're hoping to use this project as a pilot to set some standards for openness and accessibility.

For the Spectrometer project, the maintainer will be @warren, and such documentation is forthcoming -- see below!

How to contribute

We'll soon be posting draft documentation on how to edit the source production files, but basically we're going to use specially-tagged research notes as upgrade:toolname -- so, for the spectrometer, you'd tag your post upgrade:spectrometer, and callout the project maintainer in a comment, like this: @warren

To be accepted and merged into the production version, a proposal will have to meet the kit's cost, complexity, materials, and processes specifications. Part of the project team's job is to clearly document these, and to keep them simple and affordable. Actually, those are our first specs; so far, we're thinking that proposed changes must be:

  • simple, both to assemble and to manufacture
  • affordable
  • made of easy to source parts
  • broken into small parts if possible
  • manufacturable (we'll be posting more about what this means)
  • ideally in a format that's ready to be merged into our production files (again, more on this soon)
  • submitted and ready by the posted deadline

These requirements ensure that proposals meet some of our broader project goals of accessibility and cost, but also ensure that the Public Lab Kits Initiative can actually reasonably incorporate and manufacture the changes, and can plan around a known timeline. But never fear -- we'll work with folks to refine their proposals to be compatible -- that's part of the maintainer's responsibility, as mentioned above.

Ideally, and eventually, each tool page following this methodology will display:

  • a list of proposed upgrades
  • a button to post a proposal
  • guidance on what proposals must include and how to contribute

For now, for the spectrometer project, tag your proposed upgrades with upgrade:spectrometer, or click this button:

Post a spectrometer upgrade