rework version tracking file (git_verinfo.py) and scripts that write that.

Author: briantoby

GSASII/GSASIIpath.py

@@ -210,22 +210,22 @@ def HowIsG2Installed():
 def getSavedVersionInfo():
     '''Get version number information from a file written by install
     routines. This is faster than getting the information from git. Also,
-    when GSAS-II is installed into Python, the files are no longer in 
-    a git repository so querying git is not possible.
+    when GSAS-II is installed into Python, files are no longer in 
+    a git repository, so querying git is not possible.
 
-    The saved_version.py file is written by install/save_versions.py.
-    The git_verinfo.py file is written by install/tag-version.py or
-    by install/incr-mini-version.py. If both are present, use the 
-    saved_version.py file preferentially. 
+    The git_verinfo.py file is written by install/incr-version.py or 
+    by install/save_versions.py
+    The saved_version.py file was previousl written by 
+    install/save_versions.py but this file is no longer in use.
 
     :returns: a reference to the version variables or None if no 
       version info file is found.
     '''
-    try:
-        from . import saved_version as gv
-        return gv
-    except:
-        pass
+#    try:
+#        from . import saved_version as gv
+#        return gv
+#    except:
+#        pass
     try:
         from . import git_verinfo as gv
         return gv

GSASII/install/incr-version.py

@@ -136,7 +136,7 @@
     print(f'Created git version file {pyfile} at {now} for {commit0[:7]!r}')
 
     g2repo.index.add([pyfile])
-    g2repo.index.commit('increment {mode} version')
+    g2repo.index.commit(f'increment {mode} version: {versiontag}/{tagnum}')
     print('committed',pyfile,'mode=',mode)
     g2repo.remote(name='origin').push()
     g2repo.remotes.origin.push(versiontag)

GSASII/install/save-versions.py

@@ -1,4 +1,4 @@
-# record tag number and git hash into a saved_version.py file.
+# record tag number and git hash into a git_verinfo.py file.
 #
 import os
 import sys
@@ -46,7 +46,22 @@
         tagsm1 = [i for i in tags.split('\n') if i.isdecimal()]
         if not tagsm1: continue
         break
-    pyfile = os.path.join(path2GSAS2,'saved_version.py')
+    # get the latest version number
+    releases = [i for i in g2repo.tags if '.' in i.name and i.name.startswith('v')]
+    if releases:
+        majors = [i.name.split('.')[0][1:] for i in releases]
+        major = max([int(i) for i in majors if i.isdecimal()])
+        minors = [i.name.split('.')[1] for i in releases if i.name.startswith(f'v{major}.')]
+        minor = max([int(i) for i in minors if i.isdecimal()])
+        minis = [i.name.split('.',2)[2] for i in releases if i.name.startswith(f'v{major}.{minor}')]
+        # mini can be integer, float or even have letters (5.2.1.1rc1)
+        # for now, ignore anything with letters or decimals
+        mini = max([int(i) for i in minis if i.isdecimal()])
+        versiontag = f'v{major}.{minor}.{mini}'
+    else:
+        versiontag = '?'
+    # create a file with GSAS-II version information
+    pyfile = os.path.join(path2GSAS2,'git_verinfo.py')
     try:
         fp = open(pyfile,'w')
     except:
@@ -66,21 +81,7 @@
         fp.write(f'git_prevtags = {tagsm1}\n')
     else:
         fp.write(f'git_prevtags = []\n')
-    # get the latest version number
-    releases = [i for i in g2repo.tags if '.' in i.name and i.name.startswith('v')]
-    if releases:
-        majors = [i.name.split('.')[0][1:] for i in releases]
-        major = max([int(i) for i in majors if i.isdecimal()])
-        minors = [i.name.split('.')[1] for i in releases if i.name.startswith(f'v{major}.')]
-        minor = max([int(i) for i in minors if i.isdecimal()])
-        minis = [i.name.split('.',2)[2] for i in releases if i.name.startswith(f'v{major}.{minor}')]
-        # mini can be integer, float or even have letters (5.2.1.1rc1)
-        # for now, ignore anything with letters or decimals
-        mini = max([int(i) for i in minis if i.isdecimal()])
-        versiontag = f'v{major}.{minor}.{mini}'
-    else:
-        versiontag = '?'
     fp.write(f'git_versiontag = {versiontag!r}\n')
     #
     fp.close()
-    print(f'Created git version file {pyfile} at {now} for {commit0[:6]!r}')
+    print(f'Created git version file {pyfile} at {now} for {commit0[:7]!r}')

docs/source/versioning.rst

@@ -4,8 +4,8 @@ Version numbering used in GSAS-II
 Git commits
 ------------
 
-GSAS-II versions are numbered in several ways. Every time a change to one ore more 
-GSAS-II source files is committed to a repo by the git source code management system git assigns the set of changes a 40 character hexadecimal "hash" code for that version. Usually the hash code is abbreviated to the first 6-8 characters, which is still likely to be unique. We will refer to this label as the git commit number. 
+GSAS-II versions are numbered in several ways. Every time a change to one or more 
+GSAS-II source files is committed to a repo by the git source code management system, git assigns the set of changes a 40 character hexadecimal "hash" code for that version. Usually the hash code is abbreviated to the first 6-8 characters, which is still likely to be unique. We refer to this label as the git commit number. 
 
 Integer Tag numbers
 ------------------------
@@ -15,48 +15,47 @@ When a significant change is made to GSAS-II, a developer can assign an integer
 Release version numbers
 ------------------------
 
-Software packaging systems require version numbers of the form X.Y.Z, where the numbers X, Y and Z are labeled as major, minor and micro release version numbers, such as 5.1.3. X and Y are integers. Z is allowed to have a decimal place (such as 5.1.3.1) or may contain letters (such as 5.4.0rc1), but at present GSAS-II will use an integers for Z as well. The software numbering system that GSAS-II uses is intended to follow -- more or less -- the "`effective versioning <https://jacobtomlinson.dev/effver/>`_" versioning concept, as implemented below:
+Software packaging systems require version numbers of the form X.Y.Z, where the numbers X, Y and Z are labeled as major, minor and micro release version numbers, such as 5.1.3. X and Y are integers. Z is allowed to have a decimal place (such as 5.1.3.1) or may contain letters (such as 5.4.0rc1), but at present GSAS-II will use integers for Z as well. The software numbering system that GSAS-II uses is intended to follow -- more or less -- the "`effective versioning <https://jacobtomlinson.dev/effver/>`_" numbering concept, as implemented below:
 
 * The major release (starting at 5 in 2015) will be changed in GSAS-II when there are very significant changes in how the software is installed or functions that affect large portions of how the program operates. Users are advised to look carefully at the `GSAS-II home page <https://gsasii.github.io>`_ to see what has been changed.
 
-* When relatively limited new capabilities are added to GSAS-II or a change is made in how a small section of the program functions, the minor release number is incremented, such as changing from 5.1.3 to 5.2.0. (Note that when the minor release is incremented, the micro release is set to 0.) This will usually be accompanied with a  change to the integer tag number (see above). A change in the minor release indicates that while there may be some new functionality that would be useful to learn about, users can expect the GSAS-II to function pretty much as it did before, so it is not essential to consult the documentation.
+* When relatively limited new capabilities are added to GSAS-II or a change is made in how a small section of the program functions, the minor release number is incremented, such as changing from 5.1.3 to 5.2.0. (Note that when the minor release is incremented, the micro release is set to 0.) This will be accompanied with a  change to the integer tag number (see above). A change in the minor release indicates that there is some new functionality in GSAS-II that might be useful for users to learn about or a significant change due to a bug. 
 
-* Changes to the micro version are made when a bug is fixed or a cosmetic change has been applied and where a new distribution is intended. Users will normally not need to consider the details of an update when only the micro version number is incremented and may not want to update every time there is a new micro version released. However, if a user reports a but and has been told that the problem has been addressed, they will want the latest version. Likewise, before reporting a bug, users are asked to please make sure that error occurs with the latest GSAS-II version. The developers may become cross after tracking down something that has been reported as not working, only to find that problem was already fixed. Not every change (git commit) with GSAS-II will be assigned a new micro version. If the change is a development that is not completed or does not introduce any new functionality (for example improvements to documentation), a new git commit tag will be generated but the mini version will not be incremented. 
+* Changes to the micro version are made when a minor bug is fixed or a cosmetic change has been applied and where users are encouraged to update. Users will normally not need to consider the details of an update when only the micro version number is incremented and may not want to update every time there is a new micro version released. However,  users should always test GSAS-II with the latest version before reporting a bug. The developers may become unhappy after tracking down something that has been reported as not working, only to find that problem was already fixed.
+
+Not every change (git commit) for GSAS-II will be assigned a new micro version. If the change is a development that is not completed or does not introduce any new functionality (for example improvements to documentation) or is otherwise not of general interest, while a new git commit tag will be always generated, the mini version number will not be incremented. 
 
 Tools
 --------
 
-At present three scripts are provided for developers to use to create or work with integer tag and release version numbers, to save having to review the git logs for previously assigned numbers. All of these scripts update the `git_verinfo.py` version file which is kept so that non-git installs of GSAS-II can report the currect version number.
+At present two scripts are provided for developers to use to create or work with integer tag and release version numbers, to save having to review the git logs for previously assigned numbers. All of these scripts update the `git_verinfo.py` version file which is kept so that non-git installs of GSAS-II can report the currect version number.
 
-To assign a new integer tag number (and increment the minor version number), use script:
+To assign a new integer tag number and increment the mini version number, use script:
 
-   `.../GSASII/install/tag-version.py`
+   `.../GSASII/install/incr-version.py` or
+   `.../GSASII/install/incr-version.py mini`
 
-   This script is used when there are significant changes (possibly cumulative) to the
-   code and a new release should be tagged both with a new integer tag number and
-   minor version number. It updates the `git_verinfo.py` version file so that
-   GSAS-II can quickly report the current version numbers. 
+   This command is used when there have been minor changes made in GSAS-II and 
+   the changes warrent a version number update (for example, due to a bug fix). 
 
-To increment only the mini version number, use script:
+To increment the minor version number, use the script with argument "minor":
 
-   `.../GSASII/install/incr-mini-version.py`
+   `.../GSASII/install/incr-version.py minor`
 
-   This script is used when the have been minor changes made in GSAS-II and 
-   the changes warrent an update (for example, due to a bug fix). This cannot be used
-   when a new integer tag number has been assigned to the 
-   current GSAS-II commit.
-   It also updates the `git_verinfo.py` version file so that
-   GSAS-II can quickly report the current version numbers.
+   This  is used when there are significant changes (possibly cumulative) to the
+   code and a new release should be tagged both with a new integer tag number and
+   the minor version number should be increased (e.g. 5.8.2 to 5.9.0).
+
+For non-git installs, there is also this routine:
 
    `.../GSASII/install/save-versions.py`
 
-   This script is used to save the latest version info in the `saved_version.py` file.
+   This script is used to save the latest version info in the `git_verinfo.py` file.
    This file is created when a non-git install is made for GSAS-II so that the
    hash number for the current git version (which cannot be
-   placed into the `git_verinfo.py` file) is recorded. 
+   placed into the `git_verinfo.py` file by the `incr-version.py` script) is recorded. 
    The `save-versions.py` script does not change any tags or release version numbers. 
 
-
 History
 --------