cschem - design process

Terminology

• use case: a specific example that shows what the user would like to use cschem for. An use case focuses on the task, the abstract problem that is to be solved and not on how the given problem is actually solved.
• implementation: a mechanism in the design/code or a property of design/code that focuses on how something works (and not on what it would be used for)
• item: a section, typically a paragraph of one of our design document with an unique identifier. Identifiers are wrapped in braces and contain two fields separated by a colon, e.g. {pol:15}. The first field is the name of the category (e.g. pol is for policy and des is for design), the second field is an integer. If an item is removed, it's identifier is retired and never used again for another item. This helps us referencing sections of the documents.

Design document edition process

• 1. Igor2 writes a section of the design document, marked as proposal, accessible both in svn and on the project web page
• 2. Igor2 announces it on the mailing list with a deadline (probably a week or two)
• 3. contributors read the proposal, make comments, make public debates about the details
• 4. Igor2 collects and edits all the feedback and updates the proposal
• 5. it either results in a coherent, complete section or we go back to step 2 and do another cycle of refining.
• 6. when a section is finished, it is semi-closed: later sections shouldn't make significant changes to it unless it is unavoidable

The process is public and is done on the cschem mailing list and in cschem svn.

A graphical representation from a contributor's point of view:

A succesful contribution moves along the green lines, first from top down then fed back to the design proc and moves from left to right reaching the implementation. Actions among the red lines won't affect or change cschem.

The debate

• collect use cases from their practice
• make up use cases
• share the use cases (on the mailing list) - they will be collected and documented in svn
• try to apply the proposed design on these use cases and determine if the proposed implementation can reasonably handle the the use cases

In other words, the debate should first focus more on what needs to be solved than how exactly it is solved. If a contributor doesn't like an implementation proposal, (s)he should provide use cases to prove the implementation proposal is weak. An alternative implementation proposal should try to handle all (or at least most) use cases.

Cschem is a complex system - suggestions and demands will contradict each other or the availabel programmer resources or project goals. In such situations a decision has to be made, which inevitably leads to valuing some ideas, suggestions or demands higher than others or even ignoring some requests. Although the sheer crowd behind a given suggestion matters, the decision process is not democtratic: the final word is Igor2's.

Policies

In case of contradiction (e.g. between use cases), we need to differentiate between the priority of use cases. There are abstract, generic policies that may help in that.

• {pol:1} keep the implementation simple: easy to understand, easy to track, easy to (re)implement
• {pol:2} don't expect only one implementation to exist
• {pol:3} simple, common tasks should have a simple solution; if anything needs to have a complex/inconvenient solution, that needs to be the complex, rare task
• {pol:4} provide tools and building blocks, not hardwired solutions; elements of the system should make up a toolchain that can be combined in unexpected way; let the user easily recombine the elemetns
• {pol:5} do not assume the user is dumb; the tool does have a learning curve; the learning curve shouldn't be unnecessarily steep but the tool doesn't need to include "user friendly" hacks for "dummies".
• {pol:6} cschem is not gschem nor gnetlist; it is not kicad or whichever-$$$-EDA package either; we do not need to adhere to or be compatible with any old custom only because "they do that" ...
• {pol:7} ... but we should obey the Principle of Least Surprise if it doesn't result in an implementation that's too incoherent with the rest of the system.
• {pol:8} No premature optimizations. Get everything working first and then optimize.
• {pol:9} modularity: separate tasks into independent, replacable layers with clear boundaries and clean APIs between the layers. Keep layers fucused; one layer preferrably does only one thing.
• {pol:10} in the design phase, concentrate on the concepts, (what problems need to be solved and what the solution is), not on the implementation details (how exactly it is coded).