Parametrize version and file header

[JanCBrammer]

Anytime we want to change the version, we need to change it in many places (aka https://en.wikipedia.org/wiki/Shotgun_surgery), e.g., https://github.com/IUPAC-InChI/InChI_Dev/commit/87e5b133d68a7a58cb9ac94c6f7d12e066b283ef. This is error prone and tedious.

Maybe we can think of a way to parametrize the version?
I.e., keep the version in a single place (e.g., global constant), and then reference that single source of truth in all places that need the version string.

We'd then only update the version in one place if we bump it.

The same goes for the header, see e.g., https://github.com/IUPAC-InChI/InChI_Dev/commit/ac71becc16e0e454ef75abdfb820c6c7a9d9de81.

[schatzsc]

I guess you can't change the header/comment lines from inside the program itself since comments are by default static and remain as they are.

The solution that comes to my mind (but excuse my poor programming experience) would be a Python script that opens all individual files of the program, searches for the proper header line, exchanges it to the new version number it is provided with and then saves the files again.

Is this already "meta-programming"? ;-) A program that modifies another program ...

[schatzsc]

For the text output of the program, I would indeed strongly opt for a global variable that keeps the version number and is used by all other (sub)routines.

Some software - in particular those which need to be customized to different languages for the user interface - goes even further and defines all text output as "global string constants" which are read from individual language files at compile or run time.

For example, instead of

print("Please enter your data")

the code is changed to

print(STR_ENTER_INPUT)

and STR_ENTER_INPUT is then defined in different "language files", for example:

english.lng STR_ENTER_INPUT = "Please enter your data"
german.lng STR_ENTER_INPUT = "Bitte geben Sie Ihre Daten ein"
spanish.lng STR_ENTER_INPUT = "Por favor ingresa tus datos"
maori.lng STR_ENTER_INPUT = "Whakaurua koa to raraunga" ;-)

if(lang = "DE"):
language_file = "german.lng"
elif(lang = "ES"):
language_file = "spanish.lng"
elif(lang = "MI"):
language_file = "maori.lng"
else:
language_file = "english.lng"

The advantage is the easy customization to different output and languages but of course it comes at the cost that the code gets less readable directly and you need to have at least one language file open all the time in parallel.

[janholstjensen]

The solution that comes to my mind (but excuse my poor programming experience) would be a Python script that opens all individual files of the program, searches for the proper header line, exchanges it to the new version number it is provided with and then saves the files again.

I can recommend that. I use something very similar in RInChI, where a Python script can rewrite license headers before each release build.

[schatzsc]

Could you maybe share an example script with Jan Brammer?

[janholstjensen]

Sure :-). Have a look at the script here:
https://github.com/IUPAC-InChI/RInChI/blob/main/scripts/rewrite_license_headers.py

[FelixBaensch]

I don't want to advertise or anything, but I know that for Java projects in IntelliJ it is possible to add the same header or a "copyright comment" to every file via the IDE. So I did some research and with CLion, the C/C++ IDE from JetBrains, this is also possible:
https://www.jetbrains.com/help/clion/copyright.html

[giallu]

@JanCBrammer The two links you posted are 404 but I guess you are referring to the header you have on all files like this one:

InChI/INCHI-1-SRC/INCHI_API/libinchi/src/inchi_dll_a.c

Lines 1 to 7 in 7cb718f

	/*
	* International Chemical Identifier (InChI)
	* Version 1
	* Software version 1.07
	* April 30, 2024
	*
	* MIT License

Is there a reason why you want to keep the version and date in the headers? To me, the most convenient solution is to get rid of those lines everywhere

[JanCBrammer]

@giallu, intuitively, I'd also prefer getting rid of the header lines in all source files. I just can't oversee the "legal" implications. Is it sufficient to have the license in one central place? Maybe the original author(s) wanted to enable vendoring files into other projects?

[giallu]

@JanCBrammer The license at the central place (usually, a LICENSE.txt file at the root of the project) is enough to cover all the files included in the project. If a file (like sha.c) specify license terms, those takes precedence over the project ones.

However, I think just removing those 7 lines above will make your maintaner life so much easier. Every place you can remove the version/date in the sources and documentation is one less place you need to update for a new release.

As a side note, the industry standard is now moving toward specifying license in the files with SPDX, you can very much decide to embrace it and replace all the license text with something like:

// SPDX-License-Identifier: MIT

[JanCBrammer]

specifying license in the files with SPDX

Looks good, I hadn't heard of SPDX. I'm taking this to the team. If there are no objections, I'd love to introduce this to the codebase.

[giallu]

Ping me if you decide to go this path and want help with the task