pcb-rnd knowledge pool

 

Strategy

strategy by Tibor 'Igor2' Palinkas on 2018-01-06	Tags: spec, strategy
node source

 

Abstract: Specify the strategy we use for the project, for coding, documentation, community and communication.

 

project strategy

pcb-rnd targets the UNIX-minded user, thus the important aspects are:

• proper, generic data model, so we can represent and handle all sort of tricky cases
• strong CLI and automation support
• modular code so that special features can be added as plugins, without turning the code into spaghetti
• flexible support for various export and import formats
• support for a as many alien file formats as possible
• later on: strong embedded scripting support
• portability, painless compilation and installation, as-few-as-possible dependencies

Not in focus:

• GUI shine - pcb-rnd is not a modern desktop application, it doesn't have to look good according to today's standards
• proper desktop integration - we expect our users to start pcb-rnd from a shell
• web2.0 services - we expect our users to know the 1.0 tools such as email and version control

code and contribution strategy

Preferred:

• simple, C89 code (C99 for gtk)
• code structured in a way it's easy to join the project, especially working on a new plugin
• central infrastructure has to be dynamic (extensible by plugins)
• depend on minilibs instead of megalibs
• all contributors accept the generic direction of pcb-rnd and the technology being used and follow the guidelines
• contributors adapt to the development cycles and respect the timeline

documentation strategy

Preferred:

• the doc is split into a structured part (trunk/doc) and an unstructured part (pool)
• all documentation is accessible via svn
• the structured part must be self-contained and ready-to use without compilation at user's site
• both parts may have parts generated, but the generated docs have to be commited too; the generation may depend only on a list of approved tools (shell, awk, sed, grep, aagraph, graphviz)
• the unstructured part is mainly viewed on the web, but is pretty much browsable from an svn checkout too (although doesn't have to have the styling and dynamic parts)
• bulk of the documentation is written as plain text or plain, hand written html
• the doc contains high level information; low level API is documented in the corresponding .h files in plain C comments
• the unstructured part is also a call for user contribution

Not supported:

• for bulk text, non-html text language for which yet-another-tool is required jut to get a html; e.g. no pandoc, doxygen, wiki, markdown (rationale: unnecessary extra step both in language and tools compared to hand written html 1.0)
• low level documentation anywhere else than in .h files
• API doc generated from source files - API doc lives in the .h file
• documentation systems storing the files/text/data anywhere else than svn; e.g. we don't have an SQL database based documentation systems

release strategy

Source tarball releases are considered stable. pcb-rnd has scheduled releases and a rather strict timeline to give our testers enough time to test out release candidates from svn HEAD before the release.

Svn HEAD should be always compilable, developers do their best to guarantee this (although accidents happen from time to time). Brave testers may use svn HEAD for production unless otherwise announced on the mailing list.

We don't develop in forks and branches; the development is linear.

Distributions should package the latest source tarball.

communication strategy

Preferred within our community:

• almost 24/7 support on IRC
• most active users/contributors/developers should join IRC
• permanent/to-be-archived info sent to (or relayed to) the mailing list
• important info copied into the pool

Preferred within other communities:

• do not spam...
• ...but when someone has a problem that can be solved with pcb-rnd, describe the solution to that specific problem
• do generic announcements only on forums that permit this, and especially on those that already host similar announcements for other software
• don't push pcb-rnd - our goal is not to force everybody to use it; our goal is merely to help users solving their problems, with or without pcb-rnd
• ignore the trolls; we don't have to defend ourselves; confute false claims (using facts and references), ignore the rest, stay objective; 3rd party readers will recognize trolling too

Reuse vs. reinvent

Reuse when it is worth it, don't be affraid to reinvent when that's the better option.

Points to be considered before reuse:

• License compatibility
• What else does it bring? If only 10% is needed and it's larger than 2k sloc, it's probably better to avoid it
• If it's a lib, is it maintained? Don't start to depend on dead libs.
• Is it tested? Does it have a proper self-test?

Points to be considered for reinventing:

• If possible, do it as a generic minilib with some permissive license so it can be reused outside of pcb-rnd as well
• Do some research - there are usually known good ways to do what you are going to implement
• implement tests
• document the API