packaging automation

[mathematicalmichael]

how this works:
when you create a tag (via release on github, for example) - this workflow will trigger publishing the version listed under pyproject.toml. you can test that it would work (including inspecting the built artifacts) via the github action by creating PRs to master or dev. this will build and upload the artifacts to github actions (but not pypi), allowing you to catch errors early.

for example, see here: https://github.com/YingfanWang/PaCMAP/actions/runs/15859852088?pr=105 - you can download the artifacts and verify them yourself, if you so choose.

setting up trusted publishing:

• go to pypi under the pacmap management (settings) and click on "Publishing"
• under "Add a new publisher" enter the repository owner (YingfanWang) under Owner
• enter pacmap under repository name
• enter publish.yml under workflow name
• enter release-dev under environment name

setting up github environment:
for best isolation, go to this repo's settings, and under Environments create a new environment named release-dev (matching the one in the workflow).
this will allow you to have granular control over the publishing environment, without interfering with the "test that the build step works" part.

other changes:

• use of uv to manage environment (automatically generate requirements files with a know set of resolved versions). this is not forced on the users, but provided as convenience / used in the workflows (big speed up in installation + extra guarantees of stability via uv.lock)

[mathematicalmichael]

this controls which python environment is installed in the following step.

[mathematicalmichael]

this generates both wheel and sdist already

in other words, there is no need to be explicit with --wheel and --sdist as is done in the workflow (pyproject.toml defines these defaults already)

[mathematicalmichael]

@gauravrparikh ready for review.
for evidence of trusted publishing: I verified against pacmap-dev: https://github.com/mathematicalmichael/PaCMAP/actions/workflows/publish.yml

(used what I learned there to improve the workflow here with even more tightly scoped permissions by putting publish into its own step)

[mathematicalmichael]

Suggested change

	version = "0.8.1"
	version = "0.8.2rc0"

I suggest trying to create a release against this branch (or perhaps master after merge) with this same tag number, after setting up trusted publishing.

[patcon]

Suggested change

	branches: [ master, dev ]
	branches: [ master ]

[mathematicalmichael]

can't hurt, can it?

[patcon]

can't hurt, can it?

you mean, "it can't hurt [to keep it there]"? i guess not 👍

I'll assume you use it in a personal workflow or something, or aspire to propose a dev branch. regardless, if you'd prefer not to remove, it's the sort of thing I try not to care about splitting hairs over :)

[patcon]

I think I'm just unfamiliar with that's happening here. Can you explain why we're using requirements-test.txt and requirements.txt that are auto-generated from uv? Is it just to maintain backward compat for ppl who don't want to use uv? I previously assume uv.lock kinda replaced these methods.

Maybe you could explain to me via PR comment, and I can use your explanation to write inline comments to the makefile that would have helped me understand :)

[mathematicalmichael]

good question. yes, uv.lock replaces them. few reasons.

• primarily bwd compatibility (there was a set of these files before, this improves their utility by making them true frozen requirements files)
• if someone doesn't want to use uv but for some reason does want to run the test suite
• (best reason) currently, dependabot can't scan uv.lock or pyproject.toml - so having these files present allows for security scans to occur which effectively check on what's in uv.lock
• as a form of documentation in and of itself: "to create this file, use this syntax"
  technically it should be the following, though (so if one changes, so does the other):

Suggested change

	requirements-test.txt:
	uv pip compile --group dev pyproject.toml -o requirements-test.txt
	requirements.txt:
	uv pip compile pyproject.toml -o requirements.txt
	install: requirements-test.txt
	uv sync
	requirements-test.txt: pyproject.toml
	uv pip compile --group dev pyproject.toml -o requirements-test.txt
	requirements.txt: pyproject.toml
	uv pip compile pyproject.toml -o requirements.txt
	install:
	uv sync

but yeah, technically speaking, these can be removed.

[patcon]

I'm all for keeping them for backward compat, especially if core maintainers aren't quite sold on uv yet :)

• (best reason) currently, dependabot can't scan uv.lock or pyproject.toml - so having these files present allows for security scans to occur which effectively check on what's in uv.lock

but the "dependabot" rationale feels less strong. it is a bit neglected by github imho and highly locked to github infra, whereas renovate is open source and multi-platform (and is officially what uv recommends)

https://docs.astral.sh/uv/guides/integration/dependency-bots/
https://docs.renovatebot.com/bot-comparison/

[patcon]

In the end, your call -- no objection, and all this can be changed later quite easily!

[mathematicalmichael]

that's a good point.