.. include:: ../common.txt

.. _gv-developer-codecraft:
.. _tippy-gv-developer-codecraft:

:fa:`hat-wizard` Codecraft 🚧
=============================

.. readingtime::

.. |pre-commit| image:: https://results.pre-commit.ci/badge/github/bjlittle/geovista/main.svg
    :target: https://results.pre-commit.ci/latest/github/bjlittle/geovista/main

Here we provide some high-level maintenance guidelines, best practice and all-round sage
advice for contributors.


:fa:`robot` Auto-Approve Workflow
---------------------------------

:fa:`file-code` **Reference:**

- :bash:`.github/CODEOWNERS`
- :bash:`.github/workflows/ci-auto-approve.yml`

The ``main`` branch of the :guilabel:`upstream` repository has
adopted the branch protection rule which requires a :fab:`github` ``pull-request``
review approval from a designated code owner.

Trusted collaborators with sufficient privileges may request automated approval
from the :user:`geovista-bot` by submitting a ``@geovista-bot auto-approve``
comment within a :fab:`github` ``pull-request``.

:user:`bjlittle` has exclusive privileges pro tempore, pending governance
policy formulation on ``geovista`` membership of the  :fab:`github` `SciTools`_
organisation.

However, trusted collaborators have sufficient privileges to request
``@geovista-bot`` approval of third-party bot generated :fab:`github`
``pull-requests``.


:fa:`code-pull-request` Dependabot
----------------------------------

:fa:`file-code` **Reference:**

- :bash:`.github/dependabot.yml`
- :bash:`.github/workflows/*.yml` (``github-actions``)
- :bash:`requirements/pypi-*.txt` (``pip``)
- :bash:`pyproject.toml` (``pip``, ``pixi``)

We use :fab:`github` `Dependabot`_ automation to maintain `cooldown period`_
dependency version updates for both the ``github-actions`` and ``pip`` ecosystems.

Note that we adhere to the **default** `unpinned-uses`_ (`zizmor`_ v1.20.0) audit
policy for ``github-actions`` which requires **hash-pinning** on **all** actions.

We adopt a ``minor`` `pinning-strategy`_ for ``pip`` ecosystem package dependencies
and ``semver`` (default) for our ``pixi`` package dependencies.

.. attention::
    :class: dropdown

    We heavily rely on ``dependabot`` to inform us of the constant version
    updates to our package dependencies available in the ``pip`` ecosystem.

    When merging an automated ``chore`` :fa:`code-pull-request` ``pull-request``
    from ``dependabot`` ensure to confirm whether any associated ``pixi``
    package version pins also require to be updated.

    If so, then raise a separate follow-on :fa:`code-pull-request` ``pull-request``.


.. _gv-developer-codecraft-generative-ai:
.. _tippy-gv-developer-codecraft-generative-ai:

:fa:`poo-storm` Generative AI
-----------------------------

We follow the `Python Developer's Guide`_ on the use of `generative AI tools`_ for
contributing to Python projects.

In general, we recommend that contributors:

- **disclose** the use of generative AI tools in their contributions, including
  the specific tools used and the extent of their involvement
- **review**, **edit** and **test** any content generated by AI tools to ensure it
  meets the quality standards of the project and does not introduce unintended behavior
  or vulnerabilities
- **honour** the intellectual property rights of others and avoid using AI-generated
  content that may infringe on copyrights or licenses

We respect the use of generative AI tools as a means to enhance productivity and creativity,
but we also expect contributors to use these tools responsibly and ethically.

Simply put, a contributor is responsible for their contribution. We ❤️ quality contributions.


:fa:`code-branch` GitHub Collaboration Model
--------------------------------------------

We recommend that **trusted collaborators** adopt the **shared-repository** workflow,
whereby you branch **directly** within the :guilabel:`upstream` repository and
then open a :fab:`github` ``pull-request`` from that branch.

.. mermaid::
    :align: center
    :caption: Shared-Repository Workflow

    ---
    title: bjlittle / geovista
    config:
       theme: base
    ---
    gitGraph
       commit id: "46b4308"
       commit id: "3046ae3"
       branch feature
       checkout feature
       commit id: "e4010dc"
       commit id: "f31bc89"
       checkout main
       commit id: "0c135fa"
       branch bug-fix
       commit id: "d86b85b"
       checkout main
       merge feature
       commit id: "main"


This is opposed to the **forking** workflow. That involves creating your **own**
fork of the :guilabel:`upstream` repository, pushing branches to **your** fork,
then opening a :fab:`github` ``pull-request`` back to :guilabel:`upstream`. This
workflow is typically adopted by **external collaborators**.

The main benefits of the shared-repository workflow are:

- **smoother collaboration** - your colleagues can easily checkout your branch,
  review and even push fixes
- **full CI/CD access** - your :fab:`github` ``pull-request`` gets the same runners,
  secrets, and environments as :guilabel:`upstream`

Additionally, this workflow mirrors the development model adopted by the `pyvista`_
trusted collaborators.


.. comment

   🔗 URL resources in alphabetical order:


.. _cooldown period: https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-options-reference#cooldown
.. _generative AI tools: https://devguide.python.org/getting-started/generative-ai/
.. _pinning-strategy: https://pixi.prefix.dev/latest/reference/pixi_configuration/#pinning-strategy
.. _Python Developer's Guide: https://devguide.python.org/
.. _unpinned-uses: https://docs.zizmor.sh/audits/#unpinned-uses