Add automatic versioning based on Git tag

[nealkruis]

Description

Adds a script for automatic detection of Git tag information. This script populates project-specific version variables, and includes a macro that can be used to generate a "version.h" file containing preprocessor definitions for version variables.

Author Progress Checklist:

• Open draft pull request
  • Make title clearly understandable in a standalone change log context
  • Assign yourself the issue
  • Add at least one label
• Make code changes (if you haven't already)
• Self-review of code
  • My code follows the style guidelines of this project
  • I have performed a self-review of my code
  • I have added comments to my code, particularly in hard-to-understand areas
  • I have only committed the necessary changes for this fix or feature
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings
  • I have ensured that my fix is effective or that my feature works as intended by:
    • exercising the code changes in the test framework, and/or
    • manually verifying the changes (as explained in the the pull request description above)
  • My changes pass all local tests
  • My changes successfully passes CI checks
• Move pull request out of draft mode and assign reviewers
• Iterate with reviewers until all changes are approved
  • Make changes in response to reviewer comments
  • Re-request review in GitHub

Reviewer Checklist:

• Read the pull request description
• Perform a code review on GitHub
• Confirm all CI checks pass and there are no build warnings
• Pull, build, and run automated tests locally
• Perform manual tests of the fix or feature locally
• Add any review comments, if applicable
• Submit review in GitHub as either
  • Request changes, or
  • Approve
• Iterate with author until all changes are approved
• If you are the last reviewer to approve, merge the pull request and delete the branch

[spahrenk]

Seems to work in HPWHsim.

[michael-okeefe]

Is the find_package(Git) still needed on the top-level CMakeLists.txt? If not, that could be removed there.

[nealkruis]

We need git for submodule initialization too. These scripts are designed so that they can work stand-alone for any project (not just our atheneum projects). I don't think there is any harm to including it twice, though maybe both should be in their respective CMake scripts where git is invoked instead of at the top level. I'll look into it.

[michael-okeefe]

It sounds like this is a bigger discussion and, practically speaking, seems like this just works but I wonder if we should be using #pragma once vs include guards?

[nealkruis]

Yes. We should decide on this relatively soon. My big gripe about include guards is the repetitive nature of them. If someone were to create a tool that automatically applied them, I wouldn't worry as much about it. 😉

[tanaya-mankad]

I'm not sure what the current status of #pragma once is, and I know it's supported by multiple preprocessors now, but my experience is that #pragma once is not path-agnostic - so if you have a "common.h" in your project folder and also a "common.h" in some submodule or sister folder, and they both use #pragma once instead of include guards, they will both be included and potentially clash. Include guards only allow the symbol to be defined once, and the preprocessor should complain if you have two of the same file name.
I'd have to start a test project to see if this is still true.

[michael-okeefe]

Looks good, Neal and some cool features here.

This is definitely a way to do versioning.

I'll just mention that it does feel sort of funny to me to have the git tag being the single source of truth. Obviously, that works on a practical level and ties nicely into CI triggers and the like but, for example, if you downloaded the code as a zip archive or if we ever changed version control systems (hey, it's happened twice during my career thus far...), you'd have no way to determine what version you were looking at. It almost feels to me like the "git stuff" (sha, branch, build number, status, etc) is an extra layer of meta-data that's great to have if available but could be different than the version number.

Nothing to hold this up, though; just some thoughts.

[nealkruis]

Thanks, @michael-okeefe!

I don't think we'll ever be able to future proof our best practices. They will evolve, and when the next version control system comes along, we'll have to adapt.

I don't feel like we should need to support the ZIP archive version of the code. I kind of wish we could just disable it.

I think there is a lot of meta information that would be helpful to have available beyond git stuff (e.g., operating system, compiler, architecture). Plenty of fodder for the next std::pow(wow)!