Skip to content

Commit

Permalink
Update documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
ghiggi committed Apr 2, 2024
1 parent 2a15749 commit a7f252e
Show file tree
Hide file tree
Showing 9 changed files with 58 additions and 44 deletions.
2 changes: 1 addition & 1 deletion MANIFEST.in
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
prune .github
prune ci
prune data
prune docs
prune tutorials
prune ci
prune disdrodb/tests
98 changes: 56 additions & 42 deletions docs/source/maintainers_guidelines.rst
Original file line number Diff line number Diff line change
Expand Up @@ -49,36 +49,6 @@ Examples of non-breaking changes include :
- Internal function refactoring that does not affect the behavior of the software directly.


Release process
---------------

Before releasing a new version, the ``CHANGELOG.md`` file should be updated. Run

.. code-block:: bash
make changelog X.Y.Z
to update the ``CHANGELOG.md`` file with the list of issues and pull requests that have been closed since the last release.
Manually add a description to the release if necessary.

Then, commit the new ``CHANGELOG.md`` file.

.. code-block:: bash
git add CHANGELOG.md
git commit -m "update CHANGELOG.md for version X.Y.Z"
git push
Create a new tag to trigger the release process.

.. code-block:: bash
git tag -a vX.Y.Z -m "Version X.Y.Z"
git push --tags
On GitHub, edit the release description to add the list of changes from the ``CHANGELOG.md`` file.


Ongoing version support
-----------------------------------

Expand All @@ -89,8 +59,8 @@ We strongly recommend adopting the latest release of DISDRODB into production wi
The `LTE <https://www.epfl.ch/labs/lte/>`_ does not guarantee any period of support or maintenance.


Documentation pipeline
========================
Documentation
===============

DISDRODB's documentation is built using the powerful `Sphinx <https://www.sphinx-doc.org/en/master/>`_ framework,
styled with `Book Theme <https://sphinx-book-theme.readthedocs.io/en/stable/index.html>`_.
Expand Down Expand Up @@ -149,24 +119,63 @@ after each Pull Request.

This webhook is linked to the DISDRODB core developer.

.. image:: /static/documentation_pipeline.png
.. image:: /static/documentation_release.png

Ghiggi Gionata owns the `ReadTheDoc <https://readthedocs.org/>`__ account.


Package releases pipeline
============================
Package release
==================

A `GitHub Action <https://github.com/ltelab/disdrodb/actions>`_ is configured to automate the packaging and uploading process
to `PyPI <https://pypi.org/project/disdrodb/>`_.
This action, detailed `here <https://github.com/ltelab/disdrodb/blob/main/.github/workflows/release_to_pypi.yml>`_,
triggers the packaging workflow depicted in the following image:

One `GitHub Action <https://github.com/ltelab/disdrodb/actions>`_ is defined to trigger the packaging and the upload on `pypi.org <https://pypi.org/project/disdrodb/>`_.
One `GitHub Action <https://github.com/ltelab/disdrodb/actions>`_ is defined to trigger the packaging and the
upload on `pypi.org <https://pypi.org/project/disdrodb/>`_.

.. image:: /static/package_pipeline.png
.. image:: /static/package_release.png

The `PyPI <https://pypi.org/>`__ project is shared between the core contributors.
Upon the release of the package on PyPI, a conda-forge bot attempts to automatically update the
`conda-forge recipe <https://github.com/conda-forge/disdrodb-feedstock/>`__.
Once the conda-forge recipe is updated, a new conda-forge package is released.

The PyPI project and the conda-forge recipes are collaboratively maintained by core contributors of the project.


Release process
----------------

Before releasing a new version, the ``CHANGELOG.md`` file should be updated. Run

.. code-block:: bash
make changelog X.Y.Z
to update the ``CHANGELOG.md`` file with the list of issues and pull requests that have been closed since the last release.
Manually add a description to the release if necessary.

Then, commit the new ``CHANGELOG.md`` file.

.. code-block:: bash
git add CHANGELOG.md
git commit -m "update CHANGELOG.md for version X.Y.Z"
git push
Create a new tag to trigger the release process.

.. code-block:: bash
git tag -a vX.Y.Z -m "Version X.Y.Z"
git push --tags
On GitHub, edit the release description to add the list of changes from the ``CHANGELOG.md`` file.


Reviewing process
============================
====================


The main branch is protected and requires at least one review before merging.
Expand All @@ -181,10 +190,15 @@ The review process is the following:



Continuous integration (CI) testing tools
===========================================
Continuous integration
=======================

Continuous Integration (CI) is a crucial practice in modern software development, ensuring that code changes are regularly integrated into the main codebase.
With CI, each commit or pull request triggers an automated process that verifies the integrity of the codebase, runs tests,
and performs various checks to catch issues early in the development lifecycle.

The table below summarizes the software tools utilized in our CI pipeline, descibes their respective aims and project pages.

Currently, on each Pull Request, GitHub Actions are configured as follow:


+----------------------------------------------------------------------------------------------------+------------------------------------------------------------------+----------------------------------------------------------------------------------------------+
Expand Down
2 changes: 1 addition & 1 deletion docs/source/sensor_configs.rst
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
.. _sensor_configurations:

=========================
Sensor configurations
Sensor Configurations
=========================

DISDRODB tailor the processing of the disdrometer measurements according
Expand Down
Binary file modified docs/source/static/collaborative_process.png
100644 → 100755
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/source/static/collaborative_process_old.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed docs/source/static/documentation_pipeline.png
Binary file not shown.
Binary file added docs/source/static/documentation_release.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed docs/source/static/package_pipeline.png
Binary file not shown.
Binary file added docs/source/static/package_release.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit a7f252e

Please sign in to comment.