RFC: A packaging strategy for the content of the "brew-install" repo
On Monday, August 16, 2021, 6:50 PM, Elana Hashman <ehashman@debian.org> wrote:
> On Mon, Aug 16, 2021 at 04:39:24AM -0300, Leandro Doctors wrote:
Again: Thanks for your detailed original reply, Elana!
> let me know if you have any further questions.
Sorry this answer took me so many days to craft. I thought it was
important to first explicitly add the context that supports my
reasoning.
The thing is, all that ended up being quite a lot to write :-)
******************************************************************************
Summary:
In general, I agree with your proposal for a binary package dedicated
to the clojure-tools, albeit with a slightly different naming scheme.
I also present a long-term vision for the overall Clojure Debian experience,
contrasting it with the existing one.
Based on that proposed vision, the migration path I propose from the current
state of affairs reuses most of the elements from your suggestion,
albeit with some differences.
I'm sure this is by no means a perfect, flawless proposal. Chances are,
I may have forgotten some important things here. Please, do let me know
about it. After all, I'm the packaging newbie :-)
******************************************************************************
So, I have splitted my answer into different threads, corresponding to
different aspects of the "brew-install" repo: its versioning
scheme[1], its content [2], and the relationship between upstream and
Debian runner scripts [3].
[1] '"brew-install" versioning scheme' (3 messages):
https://lists.debian.org/debian-clojure/2021/08/msg00016.html
[2] 'The contents of the "brew-install" repo' (2 messages):
https://lists.debian.org/debian-clojure/2021/08/msg00019.html
[3] 'A tale of two `clojure` scripts: Upstream's vs. Debian's' (2
messages): https://lists.debian.org/debian-clojure/2021/08/msg00014.html
Luckly, Alex shared some inside information and details on those
aspects to those threads as well :-)
Thanks for that, Alex!
Anyways, now that all that has been said, I can move forward to the
core of your original message [4]
[4] https://lists.debian.org/debian-clojure/2021/08/msg00009.html
> > So... how should we integrate `clj`'s functionalily into Debian?
_(Probably, this question could have been betterly phrased as
"Defining a packaging strategy". Hence the subject of this message.)_
******************************************************************************
Summary (again):
In general, I agree with your proposal for a binary package dedicated
to the clojure-tools, albeit with a slightly different naming scheme.
I also present a long-term vision for the overall Clojure Debian experience,
contrasting it with the existing one.
Based on that proposed vision, the migration path I propose from the current
state of affaires reuses most of the elements from your suggestion,
albeit with some differences.
I'm sure this is by no means a perfect, flawless proposal. Chances are,
I may have forgotten some important things here. Please, do let me know
about it. After all, I'm the packaging newbie :-)
******************************************************************************
I can identify the following aspects:
1. Packaging the contents of the "brew-install" repo
(Already under way, and the the easiest to tackle. My only difference here
is with respect to naming. In any case, names can always be changed
while reaching to an agreement :-)
2. (IMHO) The main Problem with the current state of affairs in Debian.
3. A proposed Vision for the overall Debian Clojure experience.
4. A possible Migration Path
I will address each one of them in turn.
Please note that I have taken the liberty to reorder the quotes from
your message depending on which of these aspects they relate with.
Now, let's address these topics in order.
** 1. Packaging the contents of the "brew-install" repo **
I have already identified the elements I consider worthy of being
packaged from this repo [2].
[2] 'The contents of the "brew-install" repo' (2 messages):
https://lists.debian.org/debian-clojure/2021/08/msg00019.html
Let's move on to naming
1.1 Naming the source package
> My suggestion would be to:
> - Package the brew-install repo as source package "clojure-cli"
[...]
What about naming the source package "clojure-tools"?
- It's the name upstream uses in its uberjar,
- It describes the content of the repo we are interested in (see my
previous message).
- Moreover, chances are, the upstream Clojure developers may add in
the future to that repo more tools we may be interested in...
- Finally, on IRC you mentioned you were open to the idea :-)
That's all about source naming.
Now, let's move on to binary package naming.
1.2 Naming the binary package
> - Call this new binary package which contains the new upstream scripts
> `clj`.
I'm not so into that specific name...
I do have two possible alternatives (without any strong preference
over any of them).
What about calling that binary package `clojure-cli`? Or `clojure-cli-tools`?
(I'm not particularly favoring any of these names...)
Please, allow me to elaborate.
As per [2,3], I would like to have a binary package which would contain
- `clj` and `clojure` scripts
- the Clojure ns `clojure.run.exec` (a dependency for the `clojure` script)
- deps.edn - the initial user deps.edn file
This is all about naming and packaging the contents of the
"brew-install" repo. Now, let's move on to the next item.
** 2. The main problem with the current state of affairs in Debian. **
IMHO, our real problem here is the current content of the `clojure`
binary package.
Currently, the Debian-specific scripts partially overlap functionality
currently provided by the Clojure CLI tools, albeit *in an
incompatible way*. All the details can be found in [3].
[3] 'A tale of two `clojure` scripts: Upstream's vs. Debian's' (2
messages): https://lists.debian.org/debian-clojure/2021/08/msg00014.html
Currently, the source Debian package `src:clojure` (corresponding to
the upstream Clojure repo) provides two binary packages:
`libclojure-java` and `clojure`.
- `libclojure-java`: provides the actual upstream repo content,
- `clojure`: provides the aforementioned Debian-specific runners
Again: my point here, is that **our main problem is the current
content of the `clojure` binary package**.
Now, please allow me to describe how I envision the Clojure experience
in Debian.
** 3. A proposed Vision for the overall Debian Clojure experience. **
As a user, I would like to be able to get a working clojure
environment by installing a single metapackage. Ideally, I would like
that binary package to be named `clojure`.
That being said, I am very well aware that Debian already has a binary
`clojure` package!
So, what about the following?
- `src:clojure` only provides `libclojure-java`
(no more Debian-specific runners)
- `src:clojure-tools` provides `clojure-tools`
(for now, only with the upstream runners and a base `deps.edn` file)
- the `clojure` metapackage depends on both `libclojure-java` and
`clojure-tools`
> I'll definitely add it as a "Suggests" package (I'm debating
> "Recommends" since on most systems a "Recommends" will cause it to be
> installed by default).
I think my proposal (at least, partially) takes care of this. Chances are,
more iterations are needed here.
> My suggestion would be to:
[...]
> - Ensure that when the upstream clojure script is installed, it doesn't
> have a name collision with the existing package in Debian, which we
> need to keep for compatibility. We can potentially deprecate that
> binary package after at least one release where both are available.
> - Use alternatives to manage what /usr/bin/clojure points to.
> - Install /usr/bin/clj as is.
> That way, both packages are mutually installable and users can configure
> their alternatives as they like.
Agreed.
> If we wanted to deprecate the existing scripts [...]
I definitely think we should deprecate both Debian-specific scripts:
`clojure` and `clojurec`.
Current Debian scripts partially overlap functionality currently
provided by the Clojure CLI tools *in an incompatible way*.
In this way, if one wants to use `clojure` *today* as upstream intends
it to be used [5], the only thing one gets is.. well, confusion and
frustration. (Alex has already mentioned this - and I have to add that
this is probably the reason I have never actually used Debian's
`clojure` runner.)
[5] https://clojure.org/guides/deps_and_cli
Therefore, even though it may have been useful to have them in the
past when there was no Clojure runner at all, the very existence of
the new CLI tools has turned them into an anti-pattern[*].
[*] Anti-pattern: a solution that initially looks very promising, but
that further on leads to problems (paraphrased from [6,7]).
[6]: https://martinfowler.com/bliki/AntiPattern.html
[7]: https://www.youtube.com/watch?v=Kp5YJBQsCPE
** 4. Migration path. **
> At this point I don't think we should change what /usr/bin/clojure
> points to by default. We may want to include a NEWS file in the existing
> clojure package letting users know that clj is available once published.
Agreed, for the case the user is updating existing packages.
For the case of users installing `clojure` from scratch, I would prefer
the package to directly ship the new behavior (with the NEWS file being
displayed at install time, of course).
> [...] I'd do it over a few release cycles, e.g.
>
> 1. Release upstream clojure/clj in bookworm alongside existing scripts;
> Debian script is the default per alternatives
> 2. Increase priority of upstream scripts in next release, indicate
> Debian scripts are deprecated
> 3. Remove Debian scripts in following release
>
>
> Note that this is a very long timeframe, since we just released and each
> release cycle is approximately 2 years.
I think that being conservative here makes total sense :-)
> After it hits testing and has a couple months to soak and get user
> feedback in Debian, I also think that we should consider uploading clj
> and its dependencies to stable backports, since we just missed the
> bullseye release.
Agreed.
(Uffff.... It was LOOOONG...
Anyways, my proposal is finally done.)
Looking forward to your feedback,
Leandro
Reply to: