Define a PDS standard to manage version in python project

[tloubrieu-jpl]

Use Sean input's here and decide which or the cocktail of which options are the best fit for PDS python projects:

Sean message:
Let me look at how some of the "big name" Python projects handle it. Regardless, you want version as queryable metadata in the package's main module (i.e., init). But you also don't want to repeat yourself and have that version also in setup.py or setup.cfg.
Pillow (Python Imaging) keeps a src/PIL/_version.py and reads a version attribute using exec and compile; clever. But not compatible with the new everything-in-the-setup.cfg approach now recommended.
Requests (easy HTTP) does the same thing. Also not compatible with everything-in-the-setup.cfg.
Pandas (structured data) uses an add-on, "Versioneer". This is closer to the Maven approach, looks interesting; see https://github.com/warner/python-versioneer
Numpy (numeric and matrix) hard-codes it in setup.py then uses the PyCharm IDE to sub values into version.py from version.pyi 🤢
The Roundup Action (Yee-haw :face_with_cowboy_hat:) uses a VERSION.txt file that is read by init.py to provide the version attribute but also uses the file: syntax in the new setup.cfg support to provide by runtime and buildtime support.

[tloubrieu-jpl]

@tloubrieu-jpl will orgnize a meeting on monday for that

[nutjob4life]

👪 Meeting Summary

→ Goal: make releasing easy, error-free, and consistent:

• Easy: one-click (or push one commit, push a tag, etc.) so we spend more time developing and less time releasing
• Error-free: no mistaken releases, which can range from embarrassing to even impossible to fix (PyPI doesn't let you overwrite artifacts—problem with v0.1.2? You're pushing v0.1.3)
• Consistent: you should do the same steps whether you're on a Python or Java (Maven) project

Ideals, ideas, and observations:

• DRY to avoid inconsistency
• Focus on the main flow of development from release to release; supporting in-the-field versions/branches is something we'll be smart enough to handle on our own
• Goal is to simplify cutting a new public release
• git describe --tags is incredibly handy
• GitHub's own Draft a new release button

A note on git describe: this tool is clever enough to figure out a smart, human-readable description even if you're knee-deep in main (formerly known as master) or other feature branch work. It'll trace back the refs to find a proper release tag and then even append various things like distance from main plus partial fingerprint of the commit. It would behoove us to take advantage of it (or a tool that itself takes advantage of it).

🖥 Technologies and Standards

• Versioneer
• Semantic Release
• Maven Release Plugin
• Maven version standards, such as MAJOR.MINOR.INCREMENTAL.BUILDNUM.QUALIFIER[-SNAPSHOT]
• Python version standards, PEP440, such as TAG[+DISTANCE.gHEX[.dirty]]`
• Pre-Commit

[tloubrieu-jpl]

Question from @nutjob4life to @jordanpadams @tloubrieu-jpl what triggers the release is it a git push --tags or equivalent. or a release action in github (new release button), the later can create the tag automatically ?
@thomas is using git push --tags

[tloubrieu-jpl]

the team https://github.com/orgs/NASA-PDS/teams/pds-software-pmc is the group of people allowed to review pull request before merge. The same group should be able to create release.

[jordanpadams]

@tloubrieu-jpl also @NASA-PDS/pdsen-operations

[jordanpadams]

@tloubrieu-jpl @nutjob4life that being said, I am not stuck either way. in order to cleanup snapshots, you do need to manage tags as well. but either works.

[nutjob4life]

Let's try Versioneer with a pilot project (perhaps PDS (what other could it be?) Deep Archive?) and see how that goes. It seems closest to Maven so it should afford less errors due to the similar look-and-feel. If we like it, we can integrate it with the rest of the PDS Python-based projects.

[tloubrieu-jpl]

Ok, to start with Versionneer, @nutjob4life will test on pds-deep-archive

[tloubrieu-jpl]

@nutjob4life says we should use versionneer with setup.cfg
he will share on slack standards version numbering (e.g. PEP 440)

[tloubrieu-jpl]

Among following options:

• pep440 (also the default) = 3.9.6+1.g0cc7c45.dirty
• pep440-pre = 3.9.6.post0.dev1
• pep440-post = 3.9.6.post1.dev0+g0cc7c45
• pep440-old = 3.9.6.post1.dev0+g0cc7c45
• git-describe = 3.9.6-1-g0cc7c45
• git-describe-long = 3.9.6-1-g0cc7c45-dirty

We chose git-describe format.