Consider dropping docs/transient.texi from source distribution

[manphiz]

docs/transient.texi is generated during make docs, and it's output depends on the Emacs version when running make. This has been a source of issue that is causing transient failing to build twice-in-a-row in Debian. Relevant build failure log below (see also the Debian bug[1] regarding double-build check in Debian):

dpkg-source: info: using source format '3.0 (quilt)'
dpkg-source: info: building elpa-transient using existing ./elpa-transient_0.8.3.orig.tar.gz
dpkg-source: info: local changes detected, the modified files are:
 elpa-transient-0.8.3/docs/transient.texi
dpkg-source: error: aborting due to unexpected upstream changes, see /tmp/elpa-transient_0.8.3-1.diff.gGn3M9
dpkg-source: hint: make sure the version in debian/changelog matches the unpacked source tree
dpkg-source: hint: you can integrate the local changes with dpkg-source --commit
dpkg-buildpackage: error: dpkg-source -b . subprocess returned exit status 2

As docs/transient.texi is generated using Emacs anyway, I wonder whether it can be considered to drop it from source tarball distribution and only ship docs/transient.org, which should be sufficient.

[1] https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1044428 (Note that the bug contains build log for an earlier version which reports error for other generated files, but the idea is the same.)

[tarsius]

Consider? Doing so has been a major goal of mine for half a decade or so! I have recently given up. [Further down I realize that you are talking about the tarball, not the git repository.]

Sadly the Emacs ecosystem isn't ready for that. Maybe next decade. A few months ago, I briefly forgot about some of the reasons why I cannot do this and prematurely pulled the plug. This lead to many issues with various Emacs package managers and Emacs distributions and forced my to quickly revert.

The main problem is that Melpa does not export Org files to Texinfo, which is a bit ironic, considering that I maintain that code. I have of course implemented support in package-build.el (the tool used by Melpa) and even bubblewrapped it, but the primary Melpa maintainers don't want to use that out of an abundance of caution.

The next best thing is to remove the texi file from the "main" branch, and make Melpa get the package from a special "melpa" branch, which includes pre-build manuals. That branch would always be exactly one commit ahead of "main", which checks in the generated texi files. That's what I did a few months ago.

All hell broke lose because other projects use Melpa's recipe, with or without also using Melpa's package-build.el (and if they do, then usually a very outdated version).

Some Emacs package managers use Melpa's recipes, but make additional assumptions that Melpa does not make. For example, it is a reality that upstreams sometimes rewrite history, and Melpa can deal with that. But these package managers cannot and so they choked on my "melpa" branch. I suggested that they add a special-case; if the Melpa recipe contains :branch "melpa", then they should assume that that is only for Melpa, ignore that special value and instead just use the default branch. There are two problems with that approach.

First, these package managers also do not support generating texi from org (or so I believe), but I figure users would complain about the lack of a manual to the maintainers of these package managers, so eventually that would get sorted out.

Secondly, the maintainer of these package managers said no. They want to use Melpa's recipe their way, and if that limits what Melpa can do, then that's just how it is.

So TLDR, as much as I would love to drop this generated file, it's out of my control and I just can't.

End of rant (I hope nobody else sees this [that's why I have closed this already]).

I can only suggest workarounds:

1. In the unpack step, right after tar -x do rm docs/transient.texi. I assume it is possible to do this in a way that prevents information about that file being recorded.

2. Do touch docs/transient.texi right before make docs. I.e., prevent the bundled file from being re-generated.

3. Or better yet, run make info instead of make docs. (docs = texi info html html-dir pdf, do you really want all these outputs, especially both html and html-dir?)

Okay now I just realized that I forgot something I noticed initially. You are talking about the tarball, not the git repository. Well, I could provide a tarball without the texi file, but the thing is, I don't currently even generate a tarball. You are probably using the tarball that Github generates automatically. I don't really want to add support for generating and distributing a tarball, and then try not to forget to do that every time I create a release. (I have a package called sisyphus, which helps with generating releases, so I will probably eventually implement support for that there, but I would rather be working on other things now.)

I hope the above shows that I had to give in at about every step and that it is justified that I am tired of that. One of the above workaround, or something similar, should work, and I would prefer if you did that, even if it is a bit icky, instead of my having to take on more work.

[manphiz]

Thanks Jonas for the detailed explanation! I totally understand. I guess any non-obvious things may have a reason behind it. I actually also worked up a workaround solution in Debian so that it'll also be happy as long as the texi file is there (if you are interested please take a look at [1]), so all is good now.

As always, thank you for your work on magit and friends which make our lives much better!

[1] https://salsa.debian.org/emacsen-team/transient/-/blob/master/debian/rules?ref_type

[tarsius]

Great, thanks!

You might end up having to do the same for magit and with-editor.