Prepare for 0.4.0 PyPI release

[snake-biscuits]

Pre-release Checklist

• Latest Megatest
• Update README supported list
• Generate Latest Docs
• diff last release & finalise CHANGELOG
• Final cleanup pass
• Test python -m build (using PyPA build module)
• TestPyPI upload & test
• Upload to PyPI
• Make Git Release & Tag

Thoughts

The last PyPI release was made in late 2021.
Many refactors have occured since then.

0.3.1 is so different we don't even have useful docs for users
And so many features are missing (not to mention branch coverage)

We need to clean up the repo (excess -> bsp_tool_examples)
src/ is confusing & should probably be in another repo (need a good name)

The standards for distributing python packages have changed a lot since we last shipped.
Need to add a pyproject.toml & some other stuff probably.
All the more reason to remove excess scripts etc.

bsp_tool_examples code should also be tagged as working w/ v0.4.0 (if it works)
Gotta have a clear maintenance heirarchy:

1. bsp_tool core
2. branch scripts
3. extensions/
4. bsp_tool_examples

External projects should be tied to a fixed version.

Need to push towards a stable API & v1.0.0 ASAP
I want to stick to Semantic Versioning (Major.Minor.Patch)
This means:

• Each Minor version doesn't break the core API
• Patches only fix bugs
• Major version goes up with each serious refactor (API changes)

So long as we're in pre-alpha (0.minor.patch) things can be a little looser, but I want regular Minor releases (branch coverage)
Maintaining a decent changelog would be great for keeping updates to dependent repos small (e.g. io_import_rbsp)

RN I want to focus on performance & .bsp editing (really helps w/ research & other projects)

[snake-biscuits]

Need to add a pyproject.toml & some other stuff probably.

Looks like I added one ages back: d77ab16

Don't remember testing it tho
Got plenty of tests & docs to check over before building for PyPI anyway
Hopefully nothing major comes up, but I'll look for some current guides & best practices.

[snake-biscuits]

After doing a fair bit of reading around, here are my findings:

• The official PyPA docs are confusing¹
• setuptools has their own docs, separate from PyPA / PyPI²
• pyproject.toml can hold all the metadata for setup.py³
• awesome-pyproject links to some example repos, but they're mostly high-level
  • pypa/sampleproject has a well annotated pyproject.toml⁴
• PEP 517 & 518 standardising packages will make things easier for both users and makers⁵

Going to move all metadata into pyproject.toml
Also plan to find out if a minimal import setuptools; setuptools.setup() setup.py is optional (and could be removed)

Footnotes

1. Python Packaging User Guide >> Packaging Flow ↩

2. Setuptools Docs ↩

3. Configuing setuptools using pyproject.toml ↩

4. pypa/sampleproject on GitHub: pyproject.toml ↩

5. What the heck is pyproject.toml? ↩

[snake-biscuits]

No idea what's wrong w/ python 3.11 rn
Will make a patch release when I do

NOTE: to self: open an issue for fixing python3.11

[snake-biscuits]

Turns out you can specify "extras" in pyproject.toml
Extras allow for optional sets of dependencies, this would work great w/ extensions
bsp_tool.extensions.lightmaps already kinda works this way, but now we can formalise it

[snake-biscuits]

build got a little wierd and didn't upload the whole source tree initially
test/ subdirs also aren't shipping rn, will have to fix that later