Development Policy

These small rules help the project produce consistent and predictable output, if followed. It is not a law set in stone but highly recommended.

OpenSC functionality

• OpenSC is a gateway to key operations inside smart cards. OpenSC will not generate plaintext key material itself, but it can import plaintext keys to smart cards if requested. OpenSC implements cryptographic operations only for keys that are capable of doing it natively inside the smart card, without exposing the key to the outside world.

Wiki

• No commercial texts except one-liners like "commercial support for XXX is available from ZZZ". Wiki is not a marketing channel.
• Name things (including wiki pages) with the most appropriate name, preferably the name that appears in the official documentation of the card or product, without the extra ™ © ® symbols. This includes correct capitalization (CardOS not cardOS or CardOs).
• Wiki is semi-formal documentation. Try to write in an impersonal but friendly style and stay objective. Don't use "me" or "I" unless writing a personal comment or opinion and always include your name in parentheses if you do. But talk to the reader in a friendly way (using "You"). Avoid using "we" or "our" unless you're 100% sure that you voice the opinion of the majority of project users.
• Less is more. If possible, "do more with less words" so that the reader would not have to read 2 paragraphs to to get a 3 word fact he/she is looking for.
• Don't duplicate wiki content unless necessary and always include a link to the authoritative page.
•  http://www.full-time-writer.com/tone-in-writing.html

Source code & versioning

• Coding Style is mostly the same as the Linux kernel. Have a look at  Documentation/CodingStyle in Linux source. Most important:
  • tabs instead of spaces.
  • space before and after operands.
  •  scripts/Lindent from linux source can be useful for formatting code with indent ("-npro -kr -i8 -ts8 -sob -l80 -ss -ncs")
  • lines up to around 100..110 characters are OK, wide screens are common.
  • only C90 to allow building with MS Vistual Studio.
• something_t typedef for every struct something and use the something_t name.
• Generated files are not under version control.
• make maintainer-clean removes all generated files. See this mail on opensc-devel list.
• No new dead code (code that is commented out or between always false #ifdef-s)
• All new code must be compiled with --enable-strict and must not generate warnings.
  • Warnings about unused parameters in internal functions must not be silenced. Unused parameters in externally defined API-s can be silenced;
• SVN write access is granted to those GetInvolved with OpenSC development and
  • ask for SVN write access, if they feel they have fulfilled the criteria
  • are card driver authors/maintainers
  • have contributed at least 3 meaningful patches that get integrated
  • SVN write access is revoked after 12 months (1 year) of inactivity
  • "CVS is not a substitute for developer communication" applies to subversion as well.
  • People with write access have the moral responsibility to follow (and double-check) the opensc-commits list and make the best effort to follow the rest of this small policy.
  • Food for thought:  http://alexgaynor.net/2010/feb/25/committer-models-unladen-swallow-pypy-and-django/
  • Eventually OpenSC will move to a distribtued version control platform (git?) and SVN write access will be irrelevant.

Mailing list

• Bigger patches should go through a review process on opensc-devel (or as a Trac ticket, which is propagated to opensc-commits) for at least 3 days (72 hours) to give people time to review it. Developers have real lives as well.
• If the RFC gets no answers, the change is good to go.