X-Git-Url: https://sigrok.org/gitweb/?p=libsigrokdecode.git;a=blobdiff_plain;f=HACKING;h=9f2f14392d45779bd7a18f8e18077572ec23e521;hp=30cd1fe5425db6da688743adec6f5830610a8468;hb=HEAD;hpb=c1495906011ebabf97e799fe0f73e68ab0f1611a

diff --git a/HACKING b/HACKING
index 30cd1fe..9f2f143 100644
--- a/HACKING
+++ b/HACKING
@@ -17,6 +17,12 @@ the Python PEP-8, which includes the convention of 4 spaces for indentation:
 
   http://www.python.org/dev/peps/pep-0008/
 
+Exceptions:
+
+ - All strings should use single quotes ('foo' instead of "foo").
+
+ - No double-newlines between methods (or anywhere else).
+
 
 Contributions
 -------------
@@ -141,9 +147,22 @@ Protocol decoder guidelines
 
  - Longer, multi-line descriptions should be placed in the protocol
    decoder's __init__.py file as docstring. It can be viewed (for a specific
-   protocol decoder, e.g., UART) via "sigrok-cli -a uart", or in various
+   protocol decoder, e.g., UART) via "sigrok-cli -P uart --show", or in various
    other places in GUIs.
 
+ - Input IDs, output IDs, tags, channel IDs, option IDs, annotation class IDs,
+   annotation row IDs, and binary class IDs each must be unique.
+
+ - Annotation class IDs must not overlap with annotation row IDs.
+   For example, you cannot have an annotation row named "foo" if you already
+   have an annotation class named "foo". This avoids confusion for users
+   and simplifies e.g. command-line usage of decoders.
+
+ - Annotation class IDs should generally be singular, annotation row IDs
+   should generally be plural. Example: UART annotation classes could be
+   named "stop-bit" or "parity-bit" (singular), the annotation row containing
+   these annotation classes could be named "bits" (plural).
+
  - Generally use strings for states (of the PD state machine), not integers.
    This avoids having to keep a list of state definitions at the top of file.
    The performance overhead for this is negligible in practice.
@@ -176,6 +195,47 @@ Protocol decoder guidelines
    Not recommended:
      'FIND_ADDRESS', 'Get Temperature', 'start'
 
+ - Protocol decoder tags:
+
+   - Every decoder must have a "tags" list (>= 1 items, alphabetically sorted).
+
+   - All tag names start with a capital letter. Subsequent words of the name
+     are not capitalized, e.g. "Retro computing", "Debug/trace".
+
+   - All tag names should use singular form ("Sensor", not "Sensors").
+
+   Common tags:
+
+   - Analog/digital: Decoders related A/D conversion, e.g. ADCs and DACs.
+   - Audio: Decoders related to audio protocols, e.g. I²S, S/PDIF.
+   - Automotive: Decoders related to automotive protocols, e.g. CAN, FlexRay.
+   - Clock/timing: Decoders related to time keeping, timing, and clocks/RTCs.
+   - Debug/trace: Decoders related to microcontroller/CPU debugging, tracing,
+     programming/flashing protocols, e.g. SWD, JTAG, AVR ISP, ARM ETMv3.
+   - Display: Decoders related to display technologies, e.g. DVI, HDMI,
+     TFT, OLED, LCD, HD44780, EDID, and various LED protocols.
+   - Embedded/industrial: Decoders related to protocols used in embedded
+     systems, industrial systems, or automation (e.g. SPI, Modbus, Profibus).
+   - Encoding: Decoders related to generic encoding / line coding systems,
+     e.g. Manchester, Miller, Gray code, OOK, and similar.
+   - IC: Decoders for specific (families of) ICs (i.e. not IC-independent,
+     generic protocols like UART, SPI, CAN, or USB).
+   - IR: Decoders related to infrared (e.g. remote control) protocols.
+   - Lighting: Decoders related to lighting technologies, e.g. DALI, DMX512.
+   - Memory: Decoders related to memories (e.g. NOR/NAND flash, EEPROM,
+     SDRAM, SRAM, various other volatile or non-volatile memories).
+   - Networking: Decoders related to (wired) networking technologies.
+   - PC: Decoders related to protocols used in personal computers (desktop,
+     workstation, laptop, server). This is not meant to be restricted to
+     "IBM PC" or "x86/Intel", Apple/Commodore/Atari/SPARC etc. are fine too.
+   - RFID: Decoders related to RFID protocols, e.g. EM4100, T55xx.
+   - Retro computing: Decoders related to retro computing, e.g. MCS-48, Z80.
+   - Security/crypto: Decoders related to security or cryptography.
+   - Sensor: Decoders for sensors or all kinds, e.g. temperature or humidity.
+   - Util: Random utility/helper decoders.
+   - Wireless/RF: Decoders related to various wireless/RF technologies, e.g.
+     Bluetooth, BLE, Wifi, or 2.4GHz/433MHz custom protocols.
+
 
 Testsuite
 ---------