=================
Maintenance Guide
=================

last updated:
   April, 2026

This document outlines the procedures for maintaining the Nube application, including dependency management, code quality checks,
and build processes.

Dependency Management
=====================
This project uses `Go Modules <https://go.dev/ref/mod>`_ for dependency management.

Updating Dependencies
---------------------
To update all dependencies to their latest minor or patch versions:

.. code-block:: bash

   make update

To update a specific dependency:

.. code-block:: bash

   go get -u github.com/package/name@latest
   make tidy

Always run ``make tidy`` after updating dependencies to remove unused modules and update the ``go.sum`` file.

Verifying Dependencies
----------------------
To verify the integrity of the dependencies:

.. code-block:: bash

   go mod verify

Code Quality
============

Formatting
----------
Go code should always be formatted using ``gofmt``. To format all files in the project:

.. code-block:: bash

   make format

Linting
-------
We use standard Go tooling for static analysis.

Run ``make lint`` to perform comprehensive checks on both the Go core and the React UI.

Testing
=======
To run all unit tests in the project:

.. code-block:: bash

   make test

Building
========
To build the project binary (including embedded UI assets):

.. code-block:: bash

   make build

This will create a ``nube`` executable in the project root.

Directory Structure
===================
- ``cmd/``: Application entry points (e.g., ``cmd/nube/main.go``).
- ``internal/``: Private application and library code.
- ``docs/``: Project documentation.
- ``extras/``: Systemd units, Nautilus extensions, and desktop files.
- ``go.mod`` & ``go.sum``: Dependency definitions.

Git Hooks
=========
To ensure code quality and prevent broken builds, you should install the provided git hooks:

.. code-block:: bash

   make hooks

This will install a pre-push hook that runs ``make check`` (tests, linting, and documentation checks) before every push.

Release Process
===============
#. Ensure all tests pass: ``make test``
#. Update dependencies if necessary: ``make update``
#. Update the ``CHANGELOG.rst`` file.
#. Create a git tag for the new version:

   .. code-block:: bash

      git tag -a v0.3.2 -m "Release v0.3.2"

#. Push the tag: ``git push origin v0.3.2``.