docs: document versioned components

Author: geritwagner

docs/source/dev_docs/linter_development.rst

@@ -30,5 +30,19 @@ Best Practices
   - etc.
 - For **search field validation**, use a corresponding field mapping and helper functions like `map_to_standard()`.
 
+Deprecated syntax diagnostics
+-----------------------------
+
+Linters also warn about constructs that are deprecated in newer
+versions. Use the ``LINT_DEPRECATED_SYNTAX`` message to flag such
+patterns, for example:
+
+.. code-block:: text
+
+   LINT_2001: Operator "SAME" is deprecated. Use NEAR/0.
+
+These messages surface to users during parsing and encourage upgrades
+via translation of the query to the latest intermediate representation.
+
 .. literalinclude:: linter_skeleton.py
    :language: python

docs/source/dev_docs/overview.rst

@@ -17,4 +17,25 @@ Development setup
 
    pip install -e ".[dev]"
 
+Repository layout
+-----------------
+
+Versioned implementations live inside
+``search_query/<platform>/vX_Y_Z/`` directories:
+
+.. code-block:: text
+
+   search_query/
+       pubmed/
+           v1_0_0/
+               parser.py
+               serializer.py
+
+To add a new parser or serializer version:
+
+1. copy the latest versioned directory (e.g. ``v1_0_0`` → ``v1_1_0``),
+2. apply your changes,
+3. register the new version in ``search_query.parser.PARSERS`` or
+   ``search_query.serializer.SERIALIZERS`` so it becomes discoverable.
+
 A code skeleton is available for the parser, linter, translator, and tests.

docs/source/dev_docs/parser_development.rst

@@ -1,6 +1,28 @@
 Parser
 ============
 
+Versioned namespaces
+--------------------
+
+Parsers live in versioned modules such as
+``search_query/pubmed/v1_0_0/parser.py``. Keeping previous versions
+allows reproducible parsing and backward compatibility.
+
+The central registry in ``search_query.parser`` exposes a ``PARSERS``
+mapping and resolves the appropriate version at runtime. Calling
+``parse(..., parser_version="latest")`` loads the highest available
+version for the chosen platform.
+
+Version policy follows ``MAJOR.MINOR.PATCH`` (semantic versioning):
+
+* **MAJOR** – breaking changes in syntax.
+* **MINOR** – backward compatible features.
+* **PATCH** – bug fixes or minor improvements.
+
+When introducing a new parser version, copy the previous versioned
+directory, adjust the implementation, and register the version in the
+``PARSERS`` dictionary.
+
 
 1. Inherit from Base Classes
 -----------------------------------

docs/source/dev_docs/search_query.query.rst

@@ -1,17 +1,22 @@
-search\_query.query
+search\_query.query
 ===================
 
-.. automodule:: search_query.query
-
-
-
-
-
+The query classes implement a **generic intermediate representation (IR)**
+that abstracts away platform-specific syntax. Parsers from any platform
+produce the same tree of logical operators and terms, enabling
+cross-platform translation and version upgrades.
 
+Example round-trip:
 
+.. code-block:: python
 
+   from search_query.parser import parse
 
+   q_wos = parse('TS=("digital health")', platform='wos')
+   ir = q_wos.translate(target_syntax='generic')
+   q_back = ir.translate(target_syntax='wos')
 
+.. automodule:: search_query.query
 
    .. rubric:: Classes
 
@@ -20,3 +25,4 @@
       Query
       SearchField
       Term
+

docs/source/dev_docs/serializer_development.rst

@@ -1,6 +1,25 @@
 Serializer
 ===========
 
+Versioned serializers
+---------------------
+
+Serializer implementations live under versioned namespaces such as
+``search_query/pubmed/v1_0_0/serializer.py``. They are registered in the
+central ``search_query.serializer`` module via the ``SERIALIZERS``
+mapping. ``LATEST_SERIALIZERS`` resolves the highest semantic version at
+runtime when no explicit ``serializer_version`` is provided.
+
+Example stored query with version information:
+
+.. code-block:: json
+
+   {
+       "platform": "wos",
+       "search_string": "TS=(quantum dot)",
+       "version": "1.0.0"
+   }
+
 Serializers convert a query object into a string representation.
 This enables the query to be rendered for human inspection, logging, or submission to search engines.
 

docs/source/dev_docs/tests.rst

@@ -126,3 +126,20 @@ Example:
 
    - Use helper functions like `parser.print_tokens()` to ease debugging.
    - Use `assert ... == ...` with fallbacks for `print(...)` for inspection.
+
+4. **Golden File Tests**
+    - Purpose: Ensure that parsing and serialization remain stable across
+      versions. Store expected outputs as versioned "golden" files and
+      compare test results against them.
+
+5. **Deprecated Syntax Tests**
+    - Purpose: Verify that linters flag outdated constructs using
+      ``LINT_DEPRECATED_SYNTAX``.
+    - Example:
+
+   .. code-block:: python
+
+      def test_deprecated_operator():
+         parser = XYParser('term1 SAME term2')
+         parser.parse()
+         assert any(m['code'] == 'LINT_2001' for m in parser.linter.messages)

docs/source/load.rst

@@ -29,6 +29,7 @@ JSON files in the standard format (Haddaway et al. 2022). Example:
       "authors": [{"name": "Wagner, G.", "ORCID": "0000-0000-0000-1111"}],
       "date": {"data_entry": "2019.07.01", "search_conducted": "2019.07.01"},
       "platform": "Web of Science",
+      "version": "1.0.0",
       "database": ["SCI-EXPANDED", "SSCI", "A&HCI"],
       "search_string": "TS=(quantum AND dot AND spin)"
    }

docs/source/save.rst

@@ -16,9 +16,39 @@ To write a query to a JSON file, run the serializer:
         filename="search-file.json",
         query_str=query.to_string(platform="wos"),
         platform="wos",
+        version="1.0.0",
         authors=[{"name": "Tom Brady"}],
         record_info={},
         date={}
     )
 
     search_file.save()
+
+Backward compatibility
+----------------------
+
+Saved search strings include a ``version`` field so they can be
+re-parsed with the exact syntax they were created with:
+
+.. code-block:: json
+
+   {
+       "platform": "wos",
+       "search_string": "TS=(quantum dot)",
+       "version": "1.0.0"
+   }
+
+Queries may optionally be stored in a generic or structured form for
+redundancy:
+
+.. code-block:: json
+
+   {
+       "platform": "wos",
+       "search_string": "TS=(quantum dot)",
+       "version": "1.0.0",
+       "generic_query": "AND[quantum[TS=], dot[TS=]]"
+   }
+
+By default, search-query relies on the version pinning; the generic form
+is purely optional and mainly facilitates upgrades.