+
+Cschem is a project I plan to start within the next few years. It's goals
+and some design concepts are similar to gschem's and geda's, while it
+also breaks some traditions in order to fix shortcomings in the design of geda. It's
+named after gschem, not after geda, to emphasize that the editor needs to
+be connected more to the rest of the system (see details later).
+
+Some concepts cschem will try to follow (marking with * where there's major
+difference to geda):
+
+
1. design
+
+
1.1. modularity, aka. toolkit approach
+
1.2. flexibility (through attributes)
+
1.3. one schematics file is one sheet
+
1.4. multi page projects (hierarchic, flat)
+
1.5. data is in structured text files (no builtin sql support in core)
+
1.6. * the concept of a "project"; it's optional, tools can work on a set of schematics files _or_ on a complete project
+
1.7. * nets and components are uniquely identifiable using the same identifiers by all projects
+
1.8. * no excess "smartness" in the GUI editor: no slotting, no pin numbering, no auto renumbering, etc; these all should be done in the netlist layer and results fed back to the editor
+
1.9. * direct, bidirectional communication between the editor (GUI) and the netlist layer without any integration of the two, through simple and clean API, keeping both parts replaceable; attributes cschem got back from the netlister are "volatile": not saved, do not override attributes provided by the user
+
1.10. * less format-specific tricks built into the GUI code, more generic approaches (e.g. a search is a search, not a search-for-text-attribute and results on the result lists are any object of the design)
+
1.11. * slotting, pin mapping, device mapping are in backends
+
1.12. * back annotation should not be any harder than forward annotation
+
1.13. * since a lot of info is invented in backends, not in the GUI (e.g. pin numbers, when slotting), the GUI needs to be able to switch between "views": what (combination of) backend(s) to get these info from; Note: this would also provide an interactive DRC on the GUI with the DRC still implemented in the netlister!
+
1.14. * the scriptable plugin system is based on GPMI from the start to guarantee the tool is not tied to any one specific scripting engine or scripting language
+
+
2. implementation
+
+
2.1. a core library that does common things like figuring what objects are connected with net lines
+
2.2. the simple GUI editor should provide the frame; exotic functions should come from user plugins
+
2.3. a simple netlister that provides only generic (* absolutely no backend specific) queries; actual backends are implemented as plugins
+
2.4. * the core library and the netlister and the GUI core are all implemented in plain C:
+
+
2.4.1. * no dependency on any specific scripting engine or scripting language; no core functionality implemented in anything else but C
+
2.4.2. * no dependency on big "solves-everything" libraries (e.g. no glib or cairo dependency)
+
2.4.3. * the actual GUI is behind the plugin system (like PCB's HIDs)
+
2.4.4. * the first gui, in accordance with the no big libraries, will not be gtk or qt but sdl2 based; this would guarantee to have a front end that doesn't need to be rewritten every 5 years just for the sake of the rewrite
+
2.4.5. * scconfig instead of autotools: smaller, easier to maintain, works better outside of the gnu-win32 world
+
+
+
3. project management
+
+
3.1. automatic tests wherever possible, as early as possible
+
3.2. * VCS: simple, centralized svn with straight linear development, actively trying to avoid branching
+
3.3. * near-zero-administration releases with svn commits
+
3.4. * users should be able to submit bug reports anonymously, without having to register, without having to run javascript, java applet, flash, etc.
+
+
+
+
+
+There are a lot of open questions:
+
+
q1. how buses should work
+
q2. how slotting should work (but at least we can have alternatives here)
+
q3. how hierarchical design should work
+
q4. * how the GUI should display large amount of attributes without making the whole page an unreadable mess
+
q5. flat vs. non-flat netlists - if turns out it's not just an implementation detail in a netlister backend
+
q6. * whether project file format is a custom format or just a top sch page referencing other sch pages - pcb-rnd is leading here, there is an optional project file format already defined, so this is more or less decided
+
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
+The debate must be constructive and limited to the scope of the current
+section as much as possible. Users should:
+
+
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).
+
+
+
+Any contribution is valuable. However, any contribution costs too, not
+just for the contributor but for the community: the time to read it, test
+it, maintain it, etc. In the best contribution the cost/benefit ratio is
+strongly biased toward the benefit. This howto gives a few pointers how
+this cost/benefit ratio could be improved.
+
+
+
+
Do's
Dont's
+
+
+
+
focus: if the current design process is about aspect foo, please don't
+ write long essays on how aspect bar is affected unless it's absolutely
+ necessary to understand how foo is affected.
+
split things up; if there are 4 sections of a design doc you have
+ comments about, please start 4 separate thread for them.
+
proper referencing; if your comment is about a specific section, use
+ the section label (e.g. "{des1:4}") for reference. If the whole mail
+ or thread is about such a section, best put the reference in the subsect.
+
concentrate on what problem we need to solve, not on which
+ technology is used in the solution; e.g. "we want this part to
+ be user scriptable" is a good consideration; "we want this part
+ to be written in lua" is a bad one.
+
Generally speaking: distinguish between design and implementation details.
+ Focus on the design.
+
+
+
+
+
+
Avoid sending a single huge mail commenting every second line of a
+ chapter: that will be very hard to handle for everyone else.
+ Avoid writing verbose, especially about "background information";
+ please try to keep text as short as possible.
+
Please don't get stuck on an implementation detail; it's impossible
+ to design cschem to 100% match everybody's preference on every little
+ detail. If it matches only 70%, please live with it for now, if the
+ design is strong, it will be easy to provide alternatives later.
+
Do not hijack threads; if you want to steer the discussion in another
+ direction, it's okay to reply to a mail in a thread, but please do
+ change the topic so people know it's a new (sub)thread.
+
+