Add .git_archival.txt

[LecrisUT]

The sdist source does not include all file relevant to Fedora packaging, particularly the docs folder that is used to generate the man pages. Therefore we need to use the git archive, but for this the .git_archival.txt file is missing: https://setuptools-scm.readthedocs.io/en/latest/usage/#git-archives

[lucc]

@LecrisUT how do you build the sdist archive or where did you get it?

When I use my git checkout of alot to build it with python3 -m build --sdist the resulting archive in dist/alot-0.12.dev1+gd7fae55d.tar.gz contains a docs folder with the Makefile and the source folder.

[lucc]

In our CI in github action the python -m build task also includes the docs folder in the sdist: https://github.com/pazz/alot/actions/runs/11595604692/job/32284611750#step:5:183

[LecrisUT]

I was going by the MANIFEST.in file which should have excluded those files. Maybe setuptools changed its behavior 🤔. Well anyway this PR is good to have either way.

[lucc]

@LecrisUT are you saying that you did check your sdist now and the docs folder is actually there?

What is the reason is there to have the git_archival file? What data/functionality does it provide it for this that is not already provided by our pyproject.toml file?

If I understand the docs correctly it is a file that is modified by git archive before adding it to the output and that is read by setuptools-scm if no .git folder is available.

But I tested building an sdist from my git checkout with python -m build and the file is included in the archive but it is unmodified. So it does not contain any usable metadata. The relevant metadata is avaiable in PKG-INFO inside the sdist though. So should we exclude the git_archival file from sdist archives?

---

Can we put these settings in pyproject.toml?

[LecrisUT]

Basically this allows to run

$ pip install alot@https://github.com/pazz/alot/archive/refs/heads/master.tar.gz

Or any other commitish link. It should work with

$ pip install alot@https://github.com/pazz/alot/archive/d035110709f241cb2929a5e6b137550b17258f2d.zip

The failthrough order that setuprools-scm uses is envvar -> PKG-INFO -> .git -> .git_archival.txt. If you point pip install to a git archive it will fallthrough to the last one.

Can we put these settings in pyproject.toml?

No because this is a git issue. You can hard-code a failover version there, but that would not help packagers who need the real value from git describe

---

@LecrisUT are you saying that you did check your sdist now and the docs folder is actually there?

Sorry I was already retired for the day when I checked the replies so I didn't investigate thoroughly. The most recent pypi release does not contain the docs folder, but that one is also 6 years old. I'm not sure if setuptools has changed in the meantime and there is no simple way to double-check the CI result. Using hynek/build-and-inspect-python-package would be helpful to clarify things.

PS: I just realized the most recent tag is not on PyPI. You should setup a CD workflow there. I don't have a pure python workflow to recommend right now, but the overall structure that I recommend is this

[lucc]

@pazz I think we can merge this.

---

It seems that @geier and @dcbaker are the maintainers of the project on pypi. @pazz @geier @dcbaker I would be in favor of publishing releases to pypi via github actions. What do you think?

[pazz]

Thanks for this.
@lucc yes, I agree that automatically pushing to pypi is a good idea.