From 678d0484b4975da61fac7756f5df54d3a74fb78a Mon Sep 17 00:00:00 2001
From: Ludovic Vanasse <ludovicvanasse@gmail.com>
Date: Mon, 14 Oct 2024 00:54:42 -0400
Subject: [PATCH] Doc: Migrate Versioning and Task Names

Migrate
https://cwiki.apache.org/confluence/display/NUTTX/Versioning+and+Task+Names
to the official wiki

Signed-off-by: Ludovic Vanasse <ludovicvanasse@gmail.com>
---
 Documentation/guides/index.rst                |   1 +
 .../guides/versioning_and_task_names.rst      | 117 ++++++++++++++++++
 2 files changed, 118 insertions(+)
 create mode 100644 Documentation/guides/versioning_and_task_names.rst

diff --git a/Documentation/guides/index.rst b/Documentation/guides/index.rst
index 8a5109430da..3a3d82dd475 100644
--- a/Documentation/guides/index.rst
+++ b/Documentation/guides/index.rst
@@ -43,3 +43,4 @@ Guides
   include_files_board_h.rst
   specialstuff_in_nuttxheaderfiles.rst
   kernel_threads_with_custom_stacks.rst
+  versioning_and_task_names.rst
diff --git a/Documentation/guides/versioning_and_task_names.rst b/Documentation/guides/versioning_and_task_names.rst
new file mode 100644
index 00000000000..cebcbe5f27e
--- /dev/null
+++ b/Documentation/guides/versioning_and_task_names.rst
@@ -0,0 +1,117 @@
+=========================
+Versioning and Task Names
+=========================
+
+.. warning:: 
+    Migrated from: 
+    https://cwiki.apache.org/confluence/display/NUTTX/Versioning+and+Task+Names 
+    
+    And also seems outdated.
+
+Question
+========
+
+I have strange output from the NSH:
+
+.. code-block:: bash
+
+    nsh> sysinfo
+    System Information:
+        NuttX Version:    0.0 Build: 0
+        System Time:    1325809119 [s] UTC
+    
+    nsh> ps
+    PID   PRI SCHD TYPE   NP STATE    NAME
+        0   0 FIFO KTHREAD   READY    <noname>()
+        1  50 FIFO KTHREAD   WAITSIG  <noname>()
+        2 100 FIFO TASK      RUNNING  <noname>()
+
+No NAME and no version / build number
+
+Answer
+======
+
+This is probably normal behavior. There are two separate, unrelated issues here.
+
+Versioning
+----------
+
+There are two different ways to get NuttX: (1) You can download the versioned 
+releases at https://bitbucket.org/nuttx/nuttx/downloads, or you can (2) take 
+un-versioned snapshots from the GIT repository at 
+https://github.com/apache/nuttx. Since you have no version information, 
+I am assuming that you are using a un-versioned copy.
+
+The version number you are looking at comes from the header file 
+``nuttx/include/nuttx/version.h``. That header file was created at build time 
+from a hidden file that you can find in the top-level nuttx directory called 
+.version. For NuttX-7.10, that file looks like this:
+
+.. code-block:: bash
+
+    #!/bin/bash
+
+    CONFIG_VERSION_STRING="7.10"
+    CONFIG_VERSION_MAJOR=7
+    CONFIG_VERSION_MINOR=10
+    CONFIG_VERSION_BUILD="85981b37acc215ab795ef4ea4045f3e85a49a7af"
+
+The ``.version`` file does not exist in the GIT repository; it is was added to 
+the ``nuttx-7.10.tar.gz`` tarball when the NuttX-7.10 version was created.
+
+The ``version.h`` header file is then generated by ``tools/mkversion`` the 
+first time that you build the RTOS. That tool generates this ``version.h`` 
+header file for the above ``.version`` file:
+
+.. code-block:: c
+
+    /* version.h -- Autogenerated! Do not edit. */
+ 
+    #ifndef __INCLUDE_NUTTX_VERSION_H
+    #define __INCLUDE_NUTTX_VERSION_H
+    
+    #define CONFIG_VERSION_STRING "7.10"
+    #define CONFIG_VERSION_MAJOR 7
+    #define CONFIG_VERSION_MINOR 10
+    #define CONFIG_VERSION_BUILD "85981b37acc215ab795ef4ea4045f3e85a49a7af"
+    
+    #define CONFIG_VERSION ((CONFIG_VERSION_MAJOR << 8) | (CONFIG_VERSION_MINOR))
+    
+    #endif /* __INCLUDE_NUTTX_VERSION_H */
+
+And that is where the sysinfo command gets the version information that it 
+prints.
+
+If you are using an un-versioned snapshot of NuttX from the GIT repository, 
+then the ``.version`` file will not exist. The make system will check if there 
+is ``.version`` file every time you build. If there is no ``.version`` in the 
+top-level nuttx directory, then the make system will use the script at 
+``tools/version.sh`` to create one with version 0.0:
+
+.. code-block:: bash
+
+    $(TOPDIR)/.version:
+        $(Q) if [ ! -f .version ]; then \
+            echo "No .version file found, creating one"; \
+            tools/version.sh -v 0.0 -b 0 .version; \
+            chmod 755 .version; \
+        fi
+
+This is completely appropriate if you are using un-versioned code. You are, 
+however, free to edit the top-level ``.version`` file to generate any kind of 
+custom versioning information that you would like. It would, however, 
+probably be inappropriate to say you are using a released version when you 
+are not.
+
+Task Name Size
+--------------
+
+This one is easy. The size of a task name is controlled by the following 
+setting in your ``.config`` file:
+
+.. code-block:: c
+
+    CONFIG_TASK_NAME_SIZE=0
+
+It provides the maximum length of a task name. Zero, of course, then means no 
+task names are supported.