please complete transition to new name "kramdown-rfc"

[dkg]

159 notes that the version info still thinks it's called kramdown-rfc2629. But this is one instance of several places where the rename is not complete.

For example, the kramdown-rfc gem is basically empty, with a pointer to kramdown-rfc2629.

I'm trying to get this packaged for debian and it would be better to have it the other way around: if kramdown-rfc contained everything, and kramdown-rfc2629 was just a vestigial package that depends on kramdown-rfc. Is there some ruby-specific reason why doing such a transition won't work?

[cabo]

I did it this way because most makefiles are still using the old name, and I wanted to minimize the risk. Going on a major rename spree is not what I want to spend too much time on at this time. Do things really get easier when the balance between the gems shifts?

[cabo]

(What is a salsa project?)

[dkg]

Hi @cabo! sorry for the jargon. "salsa" is https://salsa.debian.org/, where debian hosts the packaging work for different software projects. At the moment for this gem, that's https://salsa.debian.org/ruby-team/ruby-kramdown-rfc2629 but given that upstream defaults are all referring to the kramdown-rfc name, i'd like at some point to drop the rfc2629 suffix for plain old rfc.

For now i've uploaded 1.6.6 to debian still under the old name, and added a Provides: kramdown-rfc so that "apt install kramdown-rfc" will figure out how to do the right thing.

I understand the pain of a rename scheme, and the potential risks for downstream dependencies, but i also think it can sometimes be a "rip off the bandaid" situation -- where incurring a bit of one-time pain is actually better than a drawn-out pain.

Most makefiles use the name kramdown-rfc2629 and you can of course ship that executable script with the kramdown-rfc gem. I'm not saying to drop the executable itself! I don't know how many reverse dependencies the ruby gem actually has, or how much work it would take to alias a dummy kramdown-rfc2629 gem to a more modern kramdown-rfc gem. In debian, this gem is a leaf package -- it has no reverse dependencies, though, so at least for the sake of debian's internal coherence, the rename is not as much of an issue.

(note that when you are ready to deprecate the executable script, you could just have it print a deprecation warning to stderr, and then continue doing what it used to do. after a year or two of deprecation warnings, you could yank it out)

[cabo]

I'm afraid that moving over the meat will take a bit longer than ripping off a bandaid. It is way too easy to break weird cases. There is no material downside to the current state that I can see except for some cognitive dissonance. So I apologize that I simply don't want to spend that much time on this, now. (At least I have fixed #159 now.)

[cabo]

Just looked at the thing. What would stop you from calling this kramdown-rfc?

BTW, why are you deleting doilit? This is an actual command supposed to be user-available.

[dkg]

Just so you know, i'm only recently starting to help out on the debian packaging for this, so i might not have all the answers that you want. Thanks for talking it over with me.

No worries about not changing it right away, i understand the challenges of transitions, i just wanted to let you know what might be preferable on debian's side.

As for the package name, i'd assumed that we needed ruby-kramdown-rfc2629 due to team package naming conventions (installing a particular ruby module foo ought to be apt install ruby-foo), but looking at those conventions i think i can make a reasonable argument for naming both the source and binary packages kramdown-rfc directly. I'll check with the ruby-team to see what they think. Good idea!

As for doilit, we're not deleting it, but instead shipping it as an example, i think because it was seen as experimental back in 2016. If you think it needs to be globally available i can probably transition to shipping it in the user's $PATH.

If you had some sort of documentation about what it's supposed to do and how the user should hold it that would be even more convincing ☺ -- we generally like to ship man pages with all executables, and are shipping a pretty spare manpage for kramdown-rfc. Have you thought about providing a simple manpage with the package? I could offer a patch with the raw troff format, but if you have a preference for a particular documentation-source, i'm game to try to follow it. I don't know ruby/gems well enough to figure out a reasonable way to

I'm actually a little bit concerned with pollution of the $PATH in the package as well. I can imagine claiming the binary name kdrfc for this package, but de-gfm seems out of place (wouldn't that belong better in the kramdown-parser-gfm gem)? doilit at least depends on the kramdown-rfc2629 gem directly, but its name certainly doesn't make it clear what it does.

All the binaries that have a prefix of kramdown-rfc seem like they could also be subcommands of a single high-level command (a la git). Maybe doilit belongs as one of these kind of subcommands? This kind of re-architecting is also not insignificant work, and i'm not asking you to take it on now -- just giving you a sense of what sorts of things matter when trying to integrate it into a distribution like debian.

let me know what you think!

[cabo]

Hi Daniel,

thanks a lot for doing this work.

There are a number of considerations that speak against installing applications with a system-level packing system, but as long as people are insisting on doing this, it is good to do this right.

As for the package name, i'd assumed that we needed ruby-kramdown-rfc2629 due to team package naming conventions (installing a particular ruby module foo ought to be apt install ruby-foo), but looking at those conventions https://wiki.debian.org/Teams/Ruby/Packaging/Conventions i think i can make a reasonable argument for naming both the source and binary packages kramdown-rfc directly. I'll check with the ruby-team to see what they think. Good idea!

There is a gem (ruby package) that is called “kramdown-rfc”. That just happens to have an internal dependency on “kramdown-rfc2629”. I don’t know much about Debian packaging rules, e.g., whether each of these dependencies has to be made explicit at the Debian packaging level, or whether you can have a single Debian package that installs both gems (which is what I would recommend). As for doilit, we're not deleting it, but instead shipping it as an example https://salsa.debian.org/ruby-team/ruby-kramdown-rfc2629/-/commit/7e1e5d7bafca864714b8a40b636b105434729915, i think because it was seen as experimental back in 2016. If you think it needs to be globally available i can probably transition to shipping it in the user's $PATH.

Right; I think this should be done, as a lot of documentation/instructions assume that the command is available if kramdown-rfc is available. (And I only narrowly missed adding code to kramdown-rfc commands that would assume that, too.) If you had some sort of documentation about what it's supposed to do and how the user should hold it that would be even more convincing ☺ -- we generally like to ship man pages with all executables, and are shipping a pretty spare manpage for kramdown-rfc https://manpages.debian.org/unstable/ruby-kramdown-rfc2629/kramdown-rfc.1.en.html. Have you thought about providing a simple manpage with the package? I could offer a patch with the raw troff format, but if you have a preference for a particular documentation-source, i'm game to try to follow it. I don't know ruby/gems well enough to figure out a reasonable way to

There is half a dozen executables within kramdown-rfc now; some are unrelated enough that they should have their own manpages. Ideally, they should ship with kramdown-rfc. I haven’t ever done that with my gems, so I’d need to learn how to do this (I’m a troff guy, but the way manpages are written has changed since I learned writing manpages in 1980). I'm actually a little bit concerned with pollution of the $PATH in the package as well. I can imagine claiming the binary name kdrfc for this package, but de-gfm (wouldn't that belong better in the kramdown-parser-gfm gem https://github.com/kramdown/parser-gfm?

I put it into the package as it is related to IETF tools. It is not directly RFCXML related. People have argued that the gem should be called “kramdown-ietf”, which would make more obvious why this tool is included here. de-gfm could have been done as a separate gem, but I’m a fan of “batteries included”.

(I actually put kdwatch into its own gem mainly to avoid limiting kramdown-rfc installation to systems that can install the kdwatch dependencies.)

Namespace pollution is a problem if it creates collisions. Clearly de-gfm and doilit have more potential to do that than kramdown-rfc-make-me-a-sandwich, but it is still rather moderate.

All the binaries that have a prefix of kramdown-rfc seem like they could also be subcommands of a single high-level command (a la git). This kind of re-architecting is also not insignificant work, and i'm not asking you to take it on now -- just giving you a sense of what sorts of things matter when trying to integrate it into a distribution like debian.

Well, they have way less coherence than the git subcommands. One tool manages a cache of library references, another extracts information from an XML file, a third queries doi.org http://doi.org/ and applies a ton of heuristics to turn the result into a usable citation reference, etc.

Again, thanks for this input and thanks for doing the work on the Debian side.

Grüße, Carsten

[dkg]

Thanks for the feedback, @cabo. I've got a clearer understanding of the situation now, and i think i can make most of the changes on the debian side without needing you to reorganize things, so i'll close this issue.

The debian packages are now shipping doilit directly. If you have an opportunity to write a manpage for any of the commands that this ships, i'd be happy to ship those manpages too, but that's not the same as this original ask.