docs: Modified DevOps primer, extracted guide (#20)

source/guides/contribution_checklists.rst

@@ -0,0 +1,131 @@
+
+DevOps checklist
+---------------------------
+
+This is a step-by-step guide for Tudat developers. Since Tudat is an open-source project, a developer is someone who
+wants to add or improve something within the Tudat ecosystem. This includes for instance software
+development and documentation. In this guide, we make no difference between a developer who is part of the core
+tudat team and a developer outside of it. In addition, in this guide we assume that a developer is extending
+functionalities directly from tudat `source code <https://github.com/tudat-team/tudat>`_ (in C++), which then
+requires to expose code to `tudatpy <https://github.com/tudat-team/tudatpy>`_ (in Python) and write
+associated `documentation <https://github.com/tudat-team/tudat-multidoc>`_. If a developer is not following exactly
+these steps, they may skip some of the elements in the checklist.
+
+The DevOps checklist is separated in two. One checklist is made for the developer that will for instance add features
+or documentation. The second checklist is made for the reviewer to approve and distribute the changes made by te developed.
+
+Checklist for developer
+***********************
+
+
+1. Preliminary operations:
+
+   a. Fork original `tudat <https://github.com/tudat-team/tudat>`_ repo and set original repo as upstream.
+   b. Branch out from the ``develop`` branch and open a ``feature/FEATURE_NAME`` branch (in tudat-multidoc for
+      documentation, tudatpy for code exposition to Python, etc…).
+
+2. Develop:
+
+   a. Write code for new functionalities.
+   b. Write new unit tests (in C++ and/or Python depending on the nature of the functionalities).
+   c. Run tests and experiment with the local build.
+
+3. Expose and document:
+
+   a. Expose the new C++ code in `tudatpy <https://github.com/tudat-team/tudatpy>`_ (to do so, follow the same steps in 1
+      and 2).
+   b. Write docstrings for the associated API reference in `tudat-multidoc <https://github.com/tudat-team/tudat-multidoc>`_ (to do so, follow the same steps in 1
+      and 2).
+   c. [Optional] Add further documentation on `tudat-space <https://github.com/tudat-team/tudat-space>`_ and
+      examples of new functionality in `tudatpy-examples <https://github.com/tudat-team/tudatpy-examples>`_.
+
+4. Final operations:
+
+   a. Open a Pull Request (PR) into the `develop` branch of each of the relevant repositories (for code,
+      documentation, examples, etc...).
+   b. Interact with a reviewer and, if necessary, implement the requested modifications.
+
+Checklist for reviewer
+***********************
+
+Once the PR has been approved, the reviewer (or a member of the core tudat team) will:
+
+1. Build and test new conda packages on all operating systems.
+2. If a release is needed:
+
+   a. Open release branch.
+   b. Release new version with `bumpversion`.
+   c. Release new version on Github.
+   d. Trigger build of new conda packages.
+   e. Trigger new build of documentation and release new version.
+
+.. tip::
+
+    For documentation, it is possible to merge the `feature` branch directly into `master` to speed up the process.
+
+.. note::
+
+    The steps for the reviewer will be soon automated. A beta version of such system is already in place, the current
+    status and guide can be retrieved `here <https://hackmd.io/@mJnsnK9eTqSUJ_WudSrPEQ/S1u1_2Vbc>`_.
+
+DevOps resources
+****************
+
+Below, you can find specific guides for DevOps in tudat.
+
+.. seealso:: There are also detailed guides about :ref:`Software Development` and :ref:`Software Documentation`.
+
+.. panels::
+    :column: col-lg-12 p-0
+    :header: text-secondary font-weight-bold
+
+    :fa:`github` :ref:`Code Collaboration`
+
+    ^^^
+
+    .. include:: devops/objectives/code_collaboration.rst
+
+.. panels::
+    :column: col-lg-12 p-0
+    :header: text-secondary font-weight-bold
+
+    :fa:`bullhorn` :ref:`Release versioning`
+
+    ^^^
+
+    .. include:: devops/objectives/versioning.rst
+
+
+.. panels::
+    :column: col-lg-12 p-0
+    :header: text-secondary font-weight-bold
+
+    :fa:`cubes` :ref:`Package Management`
+
+    ^^^
+
+    .. include:: devops/objectives/package_manager.rst
+
+
+.. panels::
+    :column: col-lg-12 p-0
+    :header: text-secondary font-weight-bold
+
+    :fa:`cloud-upload` :ref:`Continuous Deployment`
+
+    ^^^
+
+    .. include:: devops/objectives/continuous_deployment.rst
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Topics
+   :hidden:
+
+   devops/code_collaboration
+   devops/versioning
+   devops/package_manager
+   devops/continuous_deployment
+
+.. _test: https://www.atlassian.com/continuous-delivery/principles/continuous-integration-vs-delivery-vs-deployment

source/guides/defining_environment_variables.rst

@@ -16,7 +16,7 @@ securely store and manage sensitive information.
 Defining Environment Variables in Python
 ----------------------------------------
 
-In order to use environment variables in a Python script, you can use the `os` module. The following code snippet demonstrates how to access and use an environment variable named `MY_VARIABLE` in a Python script:
+In order to use environment variables in a Python script, you can use the ``os`` module. The following code snippet demonstrates how to access and use an environment variable named ``MY_VARIABLE`` in a Python script:
 
 .. code-block:: python
 
@@ -33,22 +33,22 @@ In order to use environment variables in a Python script, you can use the `os` m
 Defining Persistent Environment Variables in Unix
 -------------------------------------------------
 
-In Unix-based systems, environment variables can be defined persistently across terminal sessions by adding the `export` statements to your shell profile file. The location and name of this file depend on the shell you are using. For the `bash` shell, the file is typically called `.bashrc` and is located in your home directory (`~/`). For the `zsh` shell, the file is typically called `.zshrc` and is also located in your home directory (`~/`).
+In Unix-based systems, environment variables can be defined persistently across terminal sessions by adding the ``export`` statements to your shell profile file. The location and name of this file depend on the shell you are using. For the ``bash`` shell, the file is typically called ``.bashrc`` and is located in your home directory (``~/``). For the ``zsh`` shell, the file is typically called ``.zshrc`` and is also located in your home directory (``~/``).
 
-The following code snippet demonstrates how to define an environment variable named `MY_VARIABLE` in your shell profile file for the `bash` shell:
+The following code snippet demonstrates how to define an environment variable named ``MY_VARIABLE`` in your shell profile file for the ``bash`` shell:
 
 .. code-block:: bash
 
    # Add this line to your .bashrc file located in ~/
    export MY_VARIABLE="value"
 
-Note: If you are using `zsh` instead of `bash`, you would add the `export` statements to your `.zshrc` file located in your home directory (`~/`) instead of your `.bashrc` file.
+Note: If you are using ``zsh`` instead of ``bash``, you would add the ``export`` statements to your ``.zshrc`` file located in your home directory (``~/``) instead of your ``.bashrc`` file.
 
 
-Defining Temporary Environment Variables in Bash script `.sh` (Unix)
+Defining Temporary Environment Variables in Bash script ``.sh`` (Unix)
 --------------------------------------------------------------------
 
-In order to use environment variables in a Bash script, you can use the `export` keyword. The following code snippet demonstrates how to define and access an environment variable named `MY_VARIABLE` in a Bash script:
+In order to use environment variables in a Bash script, you can use the ``export`` keyword. The following code snippet demonstrates how to define and access an environment variable named ``MY_VARIABLE`` in a Bash script:
 
 .. code-block:: bash
 
@@ -66,9 +66,9 @@ In order to use environment variables in a Bash script, you can use the `export`
 Defining Environment Variables in Windows using a .bat File
 ----------------------------------------------------------
 
-In Windows, you can also define environment variables in a batch file (`.bat`) and run it to set the variables persistently.
+In Windows, you can also define environment variables in a batch file (``.bat``) and run it to set the variables persistently.
 
-To define environment variables in a batch file, you can use the `set` command, followed by the name of the variable and its value. Here's an example of setting an environment variable named `MY_VARIABLE` to the value `value` in a batch file, with an exception catch:
+To define environment variables in a batch file, you can use the ``set`` command, followed by the name of the variable and its value. Here's an example of setting an environment variable named ``MY_VARIABLE`` to the value ``value`` in a batch file, with an exception catch:
 
 .. code-block:: batch
 
@@ -80,9 +80,9 @@ To define environment variables in a batch file, you can use the `set` command,
       echo MY_VARIABLE was set successfully
    )
 
-Save this file with a `.bat` extension, for example, `set_environment_variables.bat`, and double-click on it to run it. If the environment variable was set successfully, the message "MY_VARIABLE was set successfully" will be displayed. If there was an error setting the variable, the message "MY_VARIABLE could not be set" will be displayed instead.
+Save this file with a ``.bat`` extension, for example, ``set_environment_variables.bat``, and double-click on it to run it. If the environment variable was set successfully, the message "MY_VARIABLE was set successfully" will be displayed. If there was an error setting the variable, the message "MY_VARIABLE could not be set" will be displayed instead.
 
-Note: To make the environment variable persistently available across all sessions, you can add the batch file to your startup folder, which is located at `C:\Users\<username>\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup`.
+Note: To make the environment variable persistently available across all sessions, you can add the batch file to your startup folder, which is located at ``C:\Users\<username>\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup``.
 
 Defining Persistent Environment Variables in Windows
 ----------------------------------------------------
@@ -112,21 +112,21 @@ Defining Environment Variables in an Azure Pipeline
 ---------------------------------------------------
 
 .. note::
-   This section is intended for maintainers of the feedstock repositories (at current). If you are not a maintainer, you can safely ignore this section. A more advanced guide on Azure Pipelines can be found `here <https://learn.microsoft.com/en-us/azure/devops/pipelines/process/variables>`_.
+   This section is intended for maintainers of the feedstock repositories (at current). If you are not a maintainer, you can safely ignore this section. A more advanced guide on Azure Pipelines can be found ``here <https://learn.microsoft.com/en-us/azure/devops/pipelines/process/variables>``_.
 
 1. Navigate to https://dev.azure.com/ and sign in.
 
 .. image:: graphics/azure_pipeline_1.jpeg
 
-2. Click the `feedstock-builds` project under the `tudat-team` organization (https://dev.azure.com/tudat-team).
+2. Click the ``feedstock-builds`` project under the ``tudat-team`` organization (https://dev.azure.com/tudat-team).
 
 .. image:: graphics/azure_pipeline_2.jpeg
 
-3. Click "Pipelines" under the `feedstock-builds` project.
+3. Click "Pipelines" under the ``feedstock-builds`` project.
 
 .. image:: graphics/azure_pipeline_3.jpeg
 
-4. Click on the specific pipeline in which you want to set the environment variable (e.g. `tudat-feedstock`).
+4. Click on the specific pipeline in which you want to set the environment variable (e.g. ``tudat-feedstock``).
 
 .. image:: graphics/azure_pipeline_4.jpeg
 
@@ -138,7 +138,7 @@ Defining Environment Variables in an Azure Pipeline
 
 .. image:: graphics/azure_pipeline_6.jpeg
 
-7. Update an existing token (e.g. `BINSTAR_TOKEN`), or create a new one with the `+` icon.
+7. Update an existing token (e.g. ``BINSTAR_TOKEN``), or create a new one with the ``+`` icon.
 
 .. image:: graphics/azure_pipeline_7.jpeg
 
@@ -149,6 +149,7 @@ Defining Environment Variables in an Azure Project
 --------------------------------------------------
 
 .. note::
-   This section is the desired way of defining environment variables in Azure. However, it is currently not possible to define environment variables in an Azure project due to `conda-smithy` overwriting the pipeline yaml. This is a known issue, and we are working on a solution. In the meantime, please use the method described in the previous section.
+   This section is the desired way of defining environment variables in Azure. However, it is currently not possible to define environment variables in an Azure project due to ``conda-smithy`` overwriting the pipeline yaml. This is a known issue, and we are working on a solution. In the meantime, please use the method described in the previous section.
+
+``<TODO: Add instructions on how to define environment variables in an Azure project>``_
 
-`<TODO: Add instructions on how to define environment variables in an Azure project>`_

source/index.rst

@@ -91,6 +91,7 @@ development, and documentation of Tudat.
 
    guides/defining_environment_variables
    guides/managing_access_tokens
+   guides/contribution_checklist
    guides/new_conda_package
    guides/new_forge_feedstock
    guides/new_tudat_function