search

org-roam / org-roam-bibtex

Org Roam integration with bibliography management software
GNU General Public License v3.0
565 stars 47 forks source link

Set required bibtex-completion version to 1.0.0 #275

Closed einsiedlerspiel closed 4 months ago

einsiedlerspiel commented 4 months ago

This PR sets the required version of bibtex-completion from 2.0.0 to 1.0.0, since version 2.0.0 does not exist as far as i can tell and the wrong version requirement causes problems (see https://github.com/progfolio/elpaca/issues/263).

myshevchuk commented 4 months ago

@einsiedlerspiel, well that's sort of complicated. Long before ORB has even been incepted, bibtex-completion has split off from helm-bibtex as a separate package on MELPA. The idea probably was that people would be able to pull the backend without installing the full package. In this spirit, ORB commit 8ab3a58 made bibtex-completion its requirement rather than helm-bibtex, while commit 7a08fa9 for some reason lifted the required version from 1.0.0 to 2.0.0 - could "version 1.0.0" be causing problems back then? Can't tell anymore now.

Long story short, I am reluctant to accept this pull request until further clarifications. ORB works with MELPA and mainstream package managers. I haven't had any problems in almost 4 years, nor have I heard from anybody else until now. Wouldn't these changes break the package for MELPA users? Commit 7a08fa9 didn't appear out of nowhere. What really needs consistency is helm-bibtex/bibtex-completion versioning itself. ORB will happily accept whatever current version of the latter. Could you please clarify this with @tmalsburg? Or at least make sure that changing back to version 1.0.0 won't break installing ORB with package.el or straight from MELPA.

tmalsburg commented 4 months ago

Hi there, not familiar with any of the details on your side, but there is no version 2 of bibtex-completion, so I agree that it's likely not a good idea to require it. Requiring version 1.0.0 should be perfectly fine from my perspective. Apart from that, I have to admit that version numbers of bibtex-completion and helm-bibtex are something that I shamefully neglected :)

myshevchuk commented 4 months ago

Hi @tmalsburg, thanks for your reply. Well, it's hard to hold a dispute against the package's author :) but that's not exactly correct. The situation is explained here by @progfolio. There is also this older discussion from 2016, just when you split helm-bibtex into individual packages on MELPA.

So there is a git tag "2.0.0" set on the whole git repository of helm-bibtex. And since bibtex-completion lives in the same repository, MELPA considers it to have version "2.0.0". Also, a really old ORB commit 7a08fa9 updated the required bibtex-completion version from "1.0.0" to "2.0.0". I presume because it wouldn't install from MELPA otherwise, but I'm not sure now. Anyway, requiring version "2.0.0" hasn't caused any troubles for me and other ORB users in the past 4 years until now.

I wonder if just putting another git tag "1.0.0" would solve the issue. It could be some older commit just before "2.0.0", for example. I would then change the required version back to "1.0.0". Since package managers typically pull the latest version from MELPA anyway or pin to a specific commit, theoretically no one would even notice.

Apart from that, I have to admit that version numbers of bibtex-completion and helm-bibtex are something that I shamefully neglected :)

That hasn't stopped us from using your excellent package for many years though!

tmalsburg commented 4 months ago

I'm not an expert for this package business but always happy to learn something new. I wasn't aware that git tags matter. My understanding was that the relevant info is in the header of the source file. Do git tags override this information?

progfolio commented 4 months ago

I'm not an expert for this package business but always happy to learn something new. I wasn't aware that git tags matter. My understanding was that the relevant info is in the header of the source file. Do git tags override this information?

See: https://github.com/melpa/melpa?tab=readme-ov-file#melpa-stable

In general you should keep the "Version" header field in the file in sync with the tags.

tmalsburg commented 4 months ago

Oh, I wasn't aware that we're talking about MELPA stable. I did not add my package to MELPA stable and wish that it hadn't been added. The whole concept of a stable version doesn't make any sense given our development style. I advise against using the MELPA stable version. It's safe to say that the "stable" will be less stable than the current version in the vast majority of cases.

My preferred solution would be if everyone just used the current version, but it seems the only way to achieve this would be to update version numbers and git tags on every commit, which is annoying. Any other solutions that I'm not seeing?

progfolio commented 4 months ago

I did not add my package to MELPA stable and wish that it hadn't been added. The whole concept of a stable version doesn't make any sense given our development style...

Please see https://github.com/melpa/melpa/issues/6656.

In there is mention of altering MELPA recipes to include a :version-regexp which will not match any git tags, effectively preventing future MELPA Stable releases.

My preferred solution would be if everyone just used the current version

This is what straight and Elpaca will do by default. However, Elpaca (and eventually straight) checks the versions to dependencies to ensure their minimum version requirements are met. So either, bibtex-completion needs its "Version" package header bumped to to 2.0.0, or org-roam-bibtex needs to decrease its minimum required bibtex-completion version to 1.0.0.

My preferred solution would be if everyone just used the current version, but it seems the only way to achieve this would be to update version numbers and git tags on every commit, which is annoying. Any other solutions that I'm not seeing?

Change the MELPA recipe's :version-regexp so the tags don't trigger a build there. Then you can tag whenever/however you want. But keep the Version header field up to date. Arguably it should be updated with every commit to follow semver, but that's up to you. It is what Elpaca will primarily check to determine the package's declared version.

I advise against using git tags to communicate the versioning to end users because that requires straight/Elpaca/any-other-from-source-package-manager users to download the entire repository (versus a shallow clone) to deduce the version. It also can fall out of sync with the Version header (as seen here).

myshevchuk commented 4 months ago

I've just confirmed that bibtex-completion will be pulled with no issues while installing ORB with decreased version requirement, so I'm merging this commit. Hopefully, this will solve the issue on the ORB's part.

myshevchuk commented 4 months ago

If I got it correctly, this might break installing ORB from MELPA stable, but I doubt this is really a loss.