1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
|
<html>
<body>
<h1> sch-rnd - design process </h1>
<h2> Terminology </h2>
<ul>
<li> <i>use case</i>: a specific example that shows <b>what</b> the user would
like to use cschem for. An use case focuses on the task, the abstract
problem that is to be solved and <b>not</b> on how the given problem is
actually solved.
<li> <i>implementation</i>: a mechanism in the design/code or a property
of design/code that focuses on <b>how</b> something works (and not on
what it would be used for)
<li> <i>item</i>: 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.
<tt>{pol:15}</tt>. 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.
</ul>
<H2> Design document edition process </H2>
<ul>
<li> 1. Igor2 writes a section of the design document, marked as
proposal, accessible both in svn and on the project web page
<li> 2. Igor2 announces it on the mailing list with a deadline (probably
a week or two)
<li> 3. contributors read the proposal, make comments, make public
debates about the details
<li> 4. Igor2 collects and edits all the feedback and updates the proposal
<li> 5. it either results in a coherent, complete section or we go back
to step 2 and do another cycle of refining.
<li> 6. when a section is finished, it is semi-closed: later sections
shouldn't make significant changes to it unless it is unavoidable
</ul>
<p>
The process is public and is done on the cschem mailing list and in cschem svn.
<p>
A graphical representation from a contributor's point of view:
<p>
<img src="proc.svg">
<p>
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.
<H2> The debate </H2>
The debate must be constructive and limited to the scope of the current
section as much as possible. Users should:
<ul>
<li> collect <i>use cases</i> from their practice
<li> make up <i>use cases</i>
<li> share the use cases (on the mailing list) - they will be collected and
documented in svn
<li> try to apply the proposed design on these <i>use cases</i> and determine
if the proposed <i>implementation</i> can reasonably handle the the
<i>use cases</i>
</ul>
<p>
In other words, the debate should first focus more on <b>what</b> needs to
be solved than <b>how</b> exactly it is solved. If a contributor doesn't
like an <i>implementation</i> proposal, (s)he should provide <i>use cases</i>
to prove the <i>implementation</i> proposal is weak. An alternative
<i>implementation</i> proposal should try to handle all (or at least most)
<i>use cases</i>.
<p>
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.
<H2> Policies </H2>
<p>
In case of contradiction (e.g. between <i>use cases</i>), we need to
differentiate between the priority of <i>use cases</i>. There are
abstract, generic policies that <b>may</b> help in that.
<ul>
<li> {pol:1} keep the implementation simple: easy to understand, easy to track,
easy to (re)implement
<li> {pol:2} don't expect only one implementation to exist
<li> {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
<li> {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
<li> {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".
<li> {pol:6} cschem is not gschem nor gnetlist; it is not kicad or
whichever-$$$-EDA package either; we do not <b>need to</b> adhere to
or be compatible with any old custom only because "they do that" ...
<li> {pol:7} ... but we should obey the Principle of Least Surprise if
it doesn't result in an <i>implementation</i> that's too incoherent
with the rest of the system.
<li> {pol:8} No premature optimizations. Get everything working first
and then optimize.
<li> {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.
<li> {pol:10} in the design phase, concentrate on the concepts, (<i>what</i>
problems need to be solved and what the solution is), not on the
implementation details (<i>how</i> exactly it is coded).
</ul>
|
