==================
 Teilchensammler
==================

|badge-status-pipeline|_ |badge-test-count| |badge-coverage|

----

This is a little TUI based on `Textual`_ for entering new Teilchen and for
searching for existing Teilchen. Data is kept in a sqlite database.

It has tests.

------------------
 Running tests
------------------

.. code-block:: shell

  uv run pytest
  # or, if you have just
  just test

-----------------------------
 Observing the app's console
-----------------------------

The console can be used to observe log messages, since those logs really should
not go to the terminal.

You will need two terminals:

  1. One for showing the console,
  2. The other to run the app.

Since we use uv, the incantation is a bit different from the `official
documentation`_.

In one terminal:

.. code-block:: bash

  uv run textual console
  # or if you have just
  just console

And in the other:

.. code-block:: bash

  uv run textual run --dev src/teilchensammler_cli/__init__.py
  # or if you have just
  just run-console

------------------
 Developing
------------------

To re-create bronsen's development environment (sort of), you need several
shiny new toys:

- `just`_ to run the recipes from ``justfile``
- `uv`_ for all the python executing stuff, also venv and versioning
- `prek`_ as a replacement for pre-commit
- `sphinx`_ to render reStructuredText into HTML and other formats
- `ruff`_ to lint and format the python code
- `ty`_ as LSP and type checker
- `fish`_ to be able to run all recipes

I use just; just runs uv, prek, ruff, and so on. It's indirection and
abstraction all the way down. ``just setup`` will install a few of those tools
and ``mise install`` will install a few more.

However, you can also do without all these!


~~~~~~~~~~~~~~~~~~~~~
 Commit style
~~~~~~~~~~~~~~~~~~~~~

I prefer simple commit titles. Do provide as much detail as desired in the
message's body. Commit early, commit often; rebase frequently.

~~~~~~~~~~~~~~~~~~~~~
 Tests
~~~~~~~~~~~~~~~~~~~~~

Yes! Please write tests: simple ones, trivial ones; complicated ones, slow ones.

Tests should be written in pytest fashion. Use all the plugins except brittle
ones.

~~~~~~~~~~~~~~~~~~~~~
 Notes
~~~~~~~~~~~~~~~~~~~~~

When implementing or overriding one of the ``on_*`` methods:

  - do not use ``super()``
  - maybe ``prevent_default()``
  - maybe ``event.stop()``

-------------------------------
 Bug Reports, Feature Requests
-------------------------------

Create them by clicking "Issues" at the top of the `repo page`_. Do not worry
too much about labels.

Please be specific and provide logs, screenshots, or even a test that
replicates the problem.

~~~~~~~~~~~~~~~~~~~~~~~
 Architectural Changes
~~~~~~~~~~~~~~~~~~~~~~~

These are unlikely to be accepted. This tool is not intended to scale. There
might be a web front end thing automatically provided by `Textual`_.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Configurations for tools the bronsen does not currently use
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Oh sure, I'll accept those. Please create a merge request that adds those
configuration files.

------------------
 AI
------------------

Please don't: this is my little human-created thing.

---------------------------
 Creating a new release
---------------------------

(This is so bronsen can forget.)

- run tests; make sure they pass
- commit
- ``uv version --bump {segment}``

  Where ``segment`` is one of: major, minor, patch, stable, alpha, beta, rc,
  post, dev; prefer "stable".

  Employ RC releases to make sure the pieces fit together.

- commit
- When we really really want to release:
  - make sure ``just testall`` passes
  - ``touch releasenotes.rst`` and edit that file
  - ``just release {Release Name can be several words}``
- Ponder the magnificence of what was accomplished.

.. _official documentation: https://textual.textualize.io/guide/devtools/#console
.. _Textual: https://textual.textualize.io/
.. _uv: https://astral.sh/uv
.. _ty: https://docs.astral.sh/ty/
.. _just: https://just.systems/
.. _prek: https://prek.j178.dev/
.. _ruff: https://astral.sh/ruff
.. _repo page: https://code.c-base.org/infuanfu/teilchensammler-cli
.. _fish: https://fishshell.com/#platform_tabs
.. _sphinx: https://www.sphinx-doc.org/en/master/usage/installation.html
.. |badge-test-count| image:: docs/tests-badge.svg
.. |badge-coverage| image:: docs/coverage-badge.svg
.. |badge-status-pipeline| image:: https://ci.c-base.org/api/badges/10/status.svg
.. _badge-status-pipeline: https://ci.c-base.org/repos/10