Contributing
============

Contributions are welcome. To propose a change:

#. **Open an issue, fork, and branch.** Open or identify the issue for the
   change, fork the repository, then create a branch off ``master``. Every
   contribution branch must use the ``issues/`` prefix followed by a
   kebab-case name: ``issues/<issue-number>-<short-description>`` (for
   example, ``issues/12-add-cv-generator``). Write the description in
   lowercase words separated by single hyphens — never ``snake_case``,
   camelCase, or spaces.

#. **Edit the source files.** Application code belongs in ``scripts/``, tests
   in ``tests/``, documentation in ``docs/``, and maintainer-only utilities in
   ``tools/``. Keep changes focused and add or update tests whenever behavior
   changes.

#. **Match the conventions.** Target Python 3.10 or newer, follow PEP 8, use
   ``snake_case``, add type hints where practical, and write Google-style
   docstrings. Keep lines within 88 characters. Read configuration through
   ``python-dotenv``, document new keys in ``.env.example``, and never commit a
   real ``.env`` file or secret.

#. **Keep documentation and dependencies synchronized.** Update ``README.md``
   and the relevant Sphinx pages when commands, configuration, or behavior
   change. Add runtime dependencies to both ``pyproject.toml`` and
   ``requirements.txt``; add development dependencies to ``pyproject.toml``
   and ``requirements-dev.txt``.

#. **Test before submitting.** Install the development dependencies, then run
   the project checks:

   .. code-block:: bash

      python -m pytest tests/
      python -m compileall -q scripts tests
      python -m flake8 scripts/
      python -m mypy scripts/
      python -m pydocstyle scripts/
      python -m bandit -r scripts/ -ll
      python -m isort . --profile black --check-only --diff
      python -m black . --check --diff
      python -m sphinx -W -b html docs docs/_build/html

#. **Open a pull request.** Push the ``issues/`` branch and open a PR against
   ``master``. Keep it focused, link the issue (for example, ``Fixes #123``),
   explain what changed and why, list the checks you ran, and include examples,
   command output, or screenshots when useful.

By contributing, you agree that your contribution will be licensed under the
repository's `MIT License <../LICENSE.md>`_. Be respectful in issues and pull
requests.