Developer Guide (WIP)
=====================

This guide captures engineering processes and expands as the project marches
through Alpha and beyond.

Repository Standards
--------------------

- Follow the architecture decisions recorded in ``docs/adrs``.
- Use type hints and keep ``mypy`` clean under the ``strict`` settings defined
  in ``pyproject.toml``.
- Write tests alongside features; prefer ``pytest`` parametrisation to cover
  edge cases.
- Keep documentation updates in the same change set so Sphinx builds stay
  accurate.

Coding Workflow
---------------

1. Fork the repository or create a feature branch from ``dev``.
2. Create a Python 3.11 virtual environment stored in ``.venv`` with a prompt label ``dev`` and activate it::

      python3.11 -m venv .venv --prompt dev
      source .venv/bin/activate

3. Run ``pip install -e .[dev]`` to install dependencies. This editable install
   ensures ``abssctl`` is importable in tests and CLI executions without
   tweaking ``PYTHONPATH``.
4. Implement your changes following the roadmap priorities.
5. Run linting, typing, tests, and Sphinx builds::

      ruff check src tests
      mypy src
      pytest
      sphinx-build -b html docs/source docs/_build/html

6. Open a pull request targeting ``dev`` and request review.

Testing Registry Data
---------------------

- Commands such as ``version list`` and ``instance list`` read from
  ``<state_dir>/registry/versions.yml`` and ``instances.yml``. During testing,
  create these files under a temporary ``state_dir`` (see the CLI tests for an
  example helper) to simulate installed versions or provisioned instances.
- JSON flags (``--json``) make assertions easier when validating command
  output in automated tests.
- ``version list --remote`` uses the npm CLI when available. During testing you
  can avoid network access by setting ``ABSSCTL_VERSIONS_CACHE`` to a JSON file
  containing an array of version strings or by exporting ``ABSSCTL_SKIP_NPM=1``.

Open Questions
--------------

- Release engineering automation will be defined once the PyPI project name is
  secured.
- Integration test strategy on TurnKey Linux appliances is captured in
  ``docs/adrs/ADR-030-ci-integration-tests.md``.