This repository is a template for future hardware and software projects. My project documentation used to be barren, and suffered from a pervasive mentality of "as long as someone can eventually figure out what I'm saying, then it's good enough." This is a framework to prevent that. You'll rarely want such a verbose README. Select portions relevant to your scope and audience then scrap the rest.
for the description in the top-right, it's not always possible to explain all your project does. Just describe one main feature. One concrete example is more salient and easier to understand to a would-be user than an abstraction.
- High level overview
- What was the motivation?
- Why build this project?
- What problem does it solve?
- What are current approaches to this problem, their drawbacks, or why is this problem only solvable now?
- How it works (e.g. data flow, state diagram)
- Notable features
- How it's organized:
Repository Structure Dropdown (output from tree -L 3)
├── LICENSE.md
├── README.md
├── .git/ <-- Version control information
├── .github/ <-- Configuration files like for automatically running src/tests on pushes and pull requests
├── data/ <-- Sample data, stored on Dropbox.com
│ ├── demo/ <-- Demo data called by the demo.py analysis program
│ ├── external/ <-- Data from collaborators, internet, etc
│ │ ├── README.md <-- Data source details like website, collaborator name
│ │ └── YYYYMMDD-subject/
│ ├── final/
│ │ └── YYYYMMDD-subject/ <-- Finished data called by the main.py analysis program
│ ├── interim/ <-- Processed data broken into sequential steps
│ │ ├── 1-Renamed-YYYYMMDD-subject/ <-- Results from first step in data conveyor belt
│ │ ├── 2-Cleaned-YYYYMMDD-subject/ <-- Results from second step in data conveyor belt
│ │ ├── 3-Filtered-YYYYMMDD-subject/ <-- Results from third step in data conveyor belt
│ │ └── n-TBD-YYYYMMDD-subject <-- Results from nth step in data conveyor belt
│ └── raw/ <-- Raw, unchanged, read-only data. Seperated by data category (e.g., chronological, machine/sensor type, experiment, geographic location, human subject, learning model, etc.)
│ ├── README.md <-- Experiment log including collector, time, location, data columns, units
│ └── YYYYMMDD-subject/
├── docs/ <-- All figures and logs from main.py, assets for this README, and additional documentaiton
│ ├── README.md
│ ├── BOM.numbers <-- Bill of Materials for hardware, PCB, setup procedure
│ ├── figures/ <-- Figures generated by main.py and src/sandbox/
│ ├── images/ <-- Photos and video, like of apparatus and methods
│ ├── notebook/ <-- Lab notebook with methods, observations, locations, dates, comments, experiments (repeat, redone with different parameters, new method, etc)
│ └── reports/ <-- Logs generated by main.py
├── hardware/
│ ├── CAD/ <-- Mechanical enclosures/parts/fasteners/mechanisms/etc
│ │ ├── component-1
│ │ └── component-n
│ └── PCB/
│ ├── KiCad/ <-- Printed Circut Board design file
│ ├── gerber/ <-- Printed Circut Board design file for manufacture
│ └── panelized/ <-- Printed Circut Board design file for bulk manufacture
└── src/ <-- All source code, including firmware
├── demo/ <-- Usage examples
│ └── demo_1.py
│ └── demo_n.py
├── main.py <-- **MAIN FUNCTION** that calls all actions like scripts/step_1.py
├── scripts/ <-- All scripts called by main.py
│ ├── step_1.py <-- Single-responsibility code like convert/clean/plot/download/etc
│ └── step_n.py
├── requirements.txt <-- Python dependencies
├── sandbox/ <-- Unfinished scratch work, located on seperate git branch
├── tests/
│ ├── Dockerfile <-- Automatically setup development environment
│ ├── test_1.py <-- Check performance, verify functionality (unit), verify components play nicely with each other (integration), verify if once broken feature is broken again (regression), etc
│ └── test_n.py
└── uninstall.sh <-- Remove any crud
If this is helpful in your work, please cite:
@misc{rohr2022repositorytemplate,
author = {Matthew Rohr},
title = {Repository Template},
year = {YYYY},
howpublished = {\url{https://github.com/mattrohr/repository-template}},
note = {commit xxxxxxx}
}
If you like what I do, sponsor my work through 
assume whoever is reading is a novice, and may like more guidance with explicit instructions
Hardware and software requirements like OS, chip architecture, circuits, components, sensors, controllers, effectors, and software licenses. Package manager and environment au du jour (e.g. pip, homebrew, software versions, package versions, Python venv, virtualenv).
For most users, who don't want to develop the repository-template code, installation should just be a matter of:
pip install repository-templateThe above option installs the latest released version. If you want access to the latest development version, the source code, example notebooks, and tests, you can install from source, by cloning and installing the GitHub repository:
- Clone this repository:
git clone https://github.com/mattrohr/repository-template.git && cd repository-template/- (optional, but recommended) Make and activate a virtual environment to reduce dependency conflict:
python3 -m venv venv && source venv/bin/activate- Install dependencies (
a,b,c):
python3 install -r requirement.txt && brew install docker- Run the test suite:
docker pull repository-template/standalone:1.6.3
docker run -t -i -e repository-template_OPTS='-Drepository-template.setup.test.all -Drepository-template.hostname=0.0.0.0 -Drepository-template.auth.disabled -Drepository-template.verbose' -p 3025:3025 -p 3110:3110 -p 3143:3143 -p 3465:3465 -p 3993:3993 -p 3995:3995 repository-template/standalone:1.6.3Options/flags, inputs, outputs:
| Name | Description | Default |
|---|---|---|
-f |
enforce name validation (e.g. first name, last name) | (required) |
-v |
Give verbose output | false |
-a |
Check all conditions | true |
ignore_timeout |
maximum allowed timeout before retry | (empty) |
tokens |
sign in credentials | (empty) |
timeout |
request timeout | 120 |
the quickest way for a developer to see a digestible result, like:
Consider the following table, with a missing entry in an output column.
| Name | Birthdate | Output |
|---|---|---|
| Naomi P. King | 1973 | N. King '73 |
| Gorlov Tweedledie | 2000 | G. Tweedledie '00 |
| Allie D. Buttersworth | 2022 | ? |
Flash Fil infers intent and automatically fills in the missing entry with "A. Buttersworth '22".
Perceptron Convergence Algorithm steps, variables, and parameters:
y(n) = actual response (quantized) d(n) = desired response
μ = learning-rate parameter, a positive constant less than unity
Fast Independent Component Analysis implementation:
W = rand(2,1) ;
W = W/norm(W) ;
t1 = zeros(1,d1*d2) ;
t2 = zeros(2,d1*d2) ;
a = 1.1 ;
iteration = 5;
for i = 1:iteration
i ;
W_old = W ;
t1 = tanh(a*W'*P) ;
t4 = a./(cosh(a*W'*P).*cosh(a*W'*P)) ;
t2(1,:) = P(1,:).*t1(1,:) ;
t2(2,:) = P(2,:).*t1(1,:) ;
t3 = (mean(t2'))' ;
t5 = mean(t4).*W ;
W = t3 - t5 ;
W = W/norm(W) ;
W_new = W ;
converg(i) = abs(W_new'*W_old) ;
format long
converg(i)
end
V = W'*P ;
Y = reshape(V,d1,d2);
subplot(2,3,3) ;
imshow(Y) ;
title('ICA Output') ;
imwrite(Y,'ICA-Output-1.png','png') ;Run the Demo:
python3 ./src/main.pyYou'll end up with an image / result like this:
More sophisticated examples are located in src/demo/.
-
Project status
- Active development? Is it stable? Do core features work?
- Still more to do, and this project is looking for a maintainer
- If development ceased, why? Is there a better alternative? Unforeseen and seemingly insurmountable problem? It's accomplished its goals?
-
Design process and decisions, especially non-trivial ones
- Our standard sort function performs a quick sort, but that does not preserve the order of items which we need here
- The obvious algorithm would be ABC but that fails here because x could be negative so we need the generalized form (Wikipedia link)
- Technology and technique selection and why (e.g. language choice)
- Alternative technologies and techniques and why not
- Nitty gritty of implementation
- Redundant technology/method to validate primary technology/method
- Explain what the tests test and why
- Describe evolution of prototypes (thorough mechanical example)
- What you thought would work, but didn't, and why
- Problems encountered and how you solved them
- Whenever you run into a problem note it in the log
- Checked out the code but it gave error XYZ0123, turns out I first had to upgrade component C to version 1.2 or higher
- Whenever you run into a problem note it in the log
- Performance metrics, design constraints, considerations like:
- Safety:
- security, privacy, consequences of failure modes, safety factor, consent
- Performance:
- accuracy, precision, speed, tolerance, response time, transfer rate, impact (e.g. what metrics do you have to support that you made the right decision)
- Signal:
- data (e.g. lossy/lossless format, compression, representative?, known bias), noise sources, propagation of uncertainty, error handling
- Material:
- material properties, temperature, toxicity, shelf life, weight/volume capacity
- Operation:
- system initialization (can be surprisingly tricky!), minimum number of operators, calibration, deployability, cross-platform compatibility, assembly/disassembly, installation/uninstallation, physical/electronic feedback (i.e. how easily can a user reason about its behavior when it's running), special handling, construction techniques, usability, reliability, repairability/maintainability (i.e. when things go wrong/preventative), adoptability (i.e. how transparent does the system, like machine learning algorithm, need to be in order to be adopted, what stakeholders need to sign off), accessibility, abilityability (how many -ability terms can you pad onto this considerations list before it gets weird?), location (e.g. presence of interfering ferrous material, change in ambient temperature and air pressure, magnetic field flux), planned lifetime, decay/consumables
- Economics:
- production: component sourcing, minimum order quantity, vendors, lead time, manufacturers, unit costs, gross margins, break even point, total capital requirement
- market: customer acquisition costs, lifetime value of customer, how fast is market growing? Finding previous three metrics matter way more than total market size. Market research, especially what insight do you know about getting a customer that an outsider (e.g. investor, competitor) doesn't? How many competitors?
- Safety:
-
Observations about the quality of the project
- This code can use some refactoring
- Did a quick implementation to get this to work but ABC would be better
- How do real-world results compare to initial expectations/prototype/simulation/theory. What accounts for the difference?
-
Limitations, caveats, issues that you would not want to formally record in an issue tracker
- Should make this method work for
x < 0, but that's currently out of scope
- Should make this method work for
-
To-do items / Roadmap / future directions
-
feature 1 -
performance optimizations -
feature 2 -
rewrite -
feature 3 - feature 4
- feature 5
-
-
What did you learn?
- Results? Show and tell.
- Historical context
- If nothing was discovered, significant limits have been established for future projects
- Amusing observations and stories of production
-
Helpful links
- Similar projects, even if they're not solving your same problem
- Further reading
- Links to alternative mediums describing this project (e.g. YouTube walkthrough, blogs, write-ups, podcasts, media interviews, journal/conference papers)
- Links to real world examples (e.g. if project is a module or GitHub Action and not a standalone project)
-
Contributing
- Issues / pull requests / séance prayers to bug world are welcome
- Good starter tasks and links to relevant issues/PRs
If you have questions, feel free to email Matt ([email protected]). This address is periodically changed to reduce spam.
We thank:
-
Sam Brand for his stackexchange.com answer
-
George Sun, David Larson, Diana Chien, and others at the MIT Communication Lab for their CommKit, specifically their documentation best practices, which provides refreshingly clear repository structure advice
-
Contributors, beta testers, people who provided feedback, people who made development more enjoyable or less painful or possible, authors of tutorials followed, individuals who inspired this project, individuals whose assets you used (e.g. photos, libraries), etc