So far, I've been maintaining my changelogs as regular Markdown files. A regular list of versions where each version is accompanied by a list of additions, changes, fixes, etc. But it makes it hard to display such changelogs via web UI in a nice way without dancing around the MD format. I started to think about maintaining a changelog in an EDN file. Or some other format that's not free-form. Then, generating a web UI for it (or even an MD file if someone would need it for some reason) would be trivial. Does anyone have any thoughts on this?

how to make the wide let expression prettier? when using destructing, it's very easy to have a 100+ columns' width for a line.

use newlines? can you give an example of a destructuring for of 100+ columns wide?

some code like this

(defn create-message
  [params]
  (let [{:keys [sender text token emails names group-id image-url] :as params}
        (s/conform :rtm/create-message params)

        {sender-uid :id :as sender-user}
        (impl/try-get-user-by-sender {:sender sender :token token})

        receiver-vchannel-ids
        (impl/collect-receiver-vchannel-ids sender-uid {:group-id group-id :emails emails :names names})

        [with-file? {:keys [file-mime file-name file-base64] :as file-params} :as file-conform]
        (s/conform :rtm/create-with-file? params)

        [with-tags? {:keys [tags] :as tags-params} :as tags-conform]
        (s/conform :rtm/create-with-tags? params)

        ;; Initialize processing context
        context {:params params
                 :config/file-size-limit *file-size-limit*}]

    ;; Interrupt for bad params
    (when (s/invalid? file-conform) (err/rtm-invalid-file-params))
    (when (s/invalid? tags-conform) (err/rtm-invalid-tags-params))

    ;; Processing
    (cond-> context
      (= with-file? :with)
      (impl/process-message-file! file-params)

      (= with-tags? :with)
      (impl/process-message-tags! tags-params)

      (u/external-url? image-url)
      (impl/process-message-external-image! image-url))))

I just make it use newline

Oh, I mean 100 columns, not 100 keys:joy:

@doglooksgood yeah, so use new-lines, I don't see the problem?

Personally don't like so many blank lines. If this function is shorter, it's a bit weird to have some blanks inside.

blankline != newline personally I tend to add them after hashmap kv pairs, so that my editor can align the hashmap vertically:

(defn create-message [params]
  (let [{:keys [sender text token emails names group-id image-url]
         :as   params}
        (s/conform :rtm/create-message params)
        {sender-uid :id :as sender-user}
        (impl/try-get-user-by-sender {:sender sender :token token})
        receiver-vchannel-ids
        (impl/collect-receiver-vchannel-ids sender-uid {:group-id group-id
                                                        :emails   emails
                                                        :names    names})
        [with-file? {:keys [file-mime file-name file-base64]
                     :as   file-params} :as file-conform]
        (s/conform :rtm/create-with-file? params)
        [with-tags? {:keys [tags]
                     :as   tags-params} :as tags-conform]
        (s/conform :rtm/create-with-tags? params)
        ;; Initialize processing context
        context {:params                 params
                 :config/file-size-limit *file-size-limit*}]
    ))

blank lines? I thought your problem was with line length...

right, what @vemv is showing, is what I meant

but in this case, it's hard to recognize, for example, is receiver-vchannel-ids for left or right?

that's a trade-off. either you have short lines or better readability

Linus Torvalds recently wrote about this in an e-mail..

for what? about line length?

yes: https://www.phoronix.com/scan.php?page=news_item&px=Linux-Kernel-Deprecates-80-Col

I can understand the 80 length is made for old terminals, for the code I paste, if write pair in a single line, there is another problem, that is you don't know where to split the pair

I've used the generous but real limit of 130 columns for a few years now. I chose it after github's limit (128) before it triggers horizontal scrolling With 130 I very very rarely have to reshape let bindings unnaturally So, might be a middle ground :)

this could be affected by font size?

(defn create-message
  [params]
  (let [{:keys [sender text token emails names group-id image-url] :as params} (s/conform :rtm/create-message params)
        {sender-uid :id :as sender-user} (impl/try-get-user-by-sender {:sender sender :token token})
        receiver-vchannel-ids (impl/collect-receiver-vchannel-ids sender-uid {:group-id group-id :emails emails :names names})
        [with-file? {:keys [file-mime file-name file-base64] :as file-params} :as file-conform] (s/conform :rtm/create-with-file? params)
        [with-tags? {:keys [tags] :as tags-params} :as tags-conform] (s/conform :rtm/create-with-tags? params)
        context {:params params :config/file-size-limit *file-size-limit*}]
    ...))

unless align it with C-c SPC, but that would be really wide..

Riffing off of https://clojurians.slack.com/archives/C6QH853H8/p1593191210025400 (a short thread about semantic versioning)…

(please read that entire, short thread before joining in here, or else what I say next won’t make sense 😉)

So my last question (better answered here) was “So criticism is great, but what’s the alternative?”

regarding alternatives to semver: how about never introduce breaking changes - always accrete or introduce new names via different namespaces? For actual version syntax I'm liking ISO 8601 date-based versions as it actually provides some semantic value - when the code was published, and they sort as you'd expect when treated as strings, incremental versions within the same day work by adding an integer sequence "2020-06-26" <- first version, "2020-06-26-1" <- 2nd, "2020-06-26-2" <- 3rd

Having lived through the “wild west” of C, C++ and then pre-Maven Java versioning, I have no desire to return to that disaster area.

@danvingo absolutely something worth aspiring too. But also (sadly) not always possible, and when backwards compatibility is broken (however “broken” is defined - a separate and complex topic in and of itself…) I think it’s valuable to a) communicate that in a crystal clear fashion to downstream, and b) give downstream the option to stay on the current version until such time as they can absorb the cost of upgrading and fixing the fallout from the breaking change(s).

never introducing breaking changes isn't really possible unless you you never introduce changes. obviously, there are degrees and avoiding breaking other people's code is a very valuable thing. it's one of the reason I like the clojure ecosystem generally

it seems (to me) that the crux of the debate is what information, if any, a "version" should communicate

some people think that any changes are best communicated outside of a version string (any unique identifier will do) and some people think that it's useful to have your version string communicate more (eg. size of change, time of change, etc)

https://github.com/clojure/core.async#releases-and-dependency-information is an example of not semantic versioning

How do the authors of core.async decide when to increment MAJOR vs MINOR? That page gives no indication, which doesn’t give me (as downstream) anything to base my upgrade decisions on.

The only importantant bit is "never breaks" so upgrading is always safe, at your option

At least SemVer (whether we agree with their definition or not) attempts to provide some standardisation around increments.

Just read the release notes I guess

Right, and “never breaks” would, in a SemVer world, mean that your package would have 1.MINOR.COMMITS versions “forever”, which is absolutely acceptable (and I would say even encouraged) by SemVer.

But… …if, heaven forbid, reality gets in the way of one’s carefully laid plans and one finds that a breaking change is unavoidable, SemVer gives you an “out” - roll out a 2.0.COMMITS version.

I mean I assume that’s why in more than a decade Clojure is still at 1.x.y (which, btw, I’m a huge fan of).

the thing with semantic versioning though is the decision of which number to bump is very subjective

The Clojure way would be to introduce a new name(space)

and this is always possible

and if that's really really not possible, it will just be a new lib

and if your software is always 1.minor.commits, why not just drop the 1?

Absolutely, hence why above I deliberately wrote “however “broken” is defined - a separate and complex topic in and of itself…“.

That, to me, is the fundamental crux of this question - how does one define “breakage”. The question of whether and/or how to use a version label to try to succinctly communicate that is really just a derivative of that fundamental question.

But I would assert that if you decide to use version labels to try to distill that information, SemVer is a good way to do it.

(without stating an opinion either way as to whether version labels are the “best” way to communicate breakage)

Seems like we are discussing two things here. One is what kind of versioning scheme should one use if one doesn’t use sem-ver (which includes the topic “what does 1.x.x mean when not using semver, eg core.async) and the other is how to maintain something without introducing breaking changes.

And of course a third thing, which is what is a breaking change.

I think Rich did a fairly good job of defining breakage in his talk. What I was missing is how to deal with this in my day to day life as a lib maintainer. I guess @seancorfield showed us how when he created jdbc.next instead of adding new namespaces to java.jdbc.

So I imagine that java.jdbc will only see “fixation” kind of changes, but no others.

When I started with next.jdbc, my guiding principle was that 1.0.0 would be the first stable release and I would (try to) never break anything after that. So there were months of alpha and beta releases before 1.0.0 and after a handful of 1.0.x releases I decided to go to 1.0.COMMITS to match the Contrib library moves -- and I've switched most of my libraries over to 1.0.COMMITS now.

Only the Alpha builds had breaking changes: https://github.com/seancorfield/next-jdbc/blob/develop/CHANGELOG.md#alpha-builds -- I changed to Beta only when I made my last breaking change (renaming reducible! to plan). I am fairly certain there have been no breaking changes since then, just additions and some bug fixes.

(I suppose you could argue that bug fixes are "breaking" insofar as they change the behavior of programs that "rely on those bugs")

clojure.java.jdbc will only get important bug fixes at this point -- no new features. Unless someone else decides to take over as maintainer and evolve it (but I'd much rather they contribute to next.jdbc at this point).

My experiences with many supposed "SemVer"-based projects is that they do still break stuff in patch and minor releases sometimes, and when they bump major versions for breaking changes you just end up with runaway version numbers... so I'm in the "SemVer is pretty meaningless camp".

It seems that a reasonable criticism of common practice is that "if they really followed SemVer, they would be at version 72.x.y instead of 3.a.b". That is a problem of how it is followed, and there are marketing/sales/don't-scare-the-customer-away reasons commonly given for "don't increase the major version number if you can rationalize your way out of it".

I will probably bump next.jdbc to 1.1.COMMITS when I merge in either the nested TX control stuff or the multiple result set support (and bump to 1.2.COMMITS when I merge in whichever is the second of those features). I could imagine bumping to 2.0.COMMITS if I added in a whole new set of functionality (such as, maybe, adding in a full DSL for composable SQL queries a la HoneySQL which I also maintain these days).

And not only marketing/sales/whatever that engineers often criticize (sometimes with good justification), but engineers themselves do it, without being prodded by marketing/sales/whoever

I like the .commits so you can just compare the last number for "newer". I might adopt it but then probably counting releases, not commits

at the limit bumping major version numbers just becomes the commit count anyway

which is what the underscore guy did for underscore-semver I believe

But that then loses the “breakage” information.

I thought he just multiplied the version number by 100? v170.0.0 instead of v1.7.0

i.e. you’re no longer communicating breakage via version label

(which again, I don’t have a strong opinion of either way)

it is

every change may break some behavior someone relies on, so to be safe bump the major

Only in the sense of “every single version breaks”.

Which is a rather large tax to impose downstream.

"every single version potentially breaks"

only if downstream believes in semver to the point that they don't bother to review upstream stuff unless there is a major version bump

There are also camps that don't care about breaking, "the type system will just give them a TODO list"

🔥

@seancorfield if I have to go and do a bunch of legwork to determine, for every single version, whether it contains breaking changes or not, the net effect is much the same as if every version absolutely does contain breaking changes.

But then perhaps living life defensively is ok for some? ¯\(ツ)/¯

there have been breakages in clojure, like now you will get an error if you use require in the ns macro instead of :require

yeah, or something with :import also changes (a spec macro check will throw)

which caused a number of projects to have to update

The only breakage I can recall experiencing myself was in 1.10.0, which (given I’ve been using it since 1.2 or so) is a pretty fantastic record.

I’ve been very grateful that I don’t have to be as defensive when using Clojure.

from the perspective of users, a breaking change, from the perspective of the rhickey, require was always wrong, but just lacked checking

so maybe a minor bump, a case that was always incorrect now throws an error

I assume rejecting :0 and : were considered but weren't important enough to break code that relied on them

@hiredman Right - you’re diving down the “what does ‘breaking’ even mean” arm of the discussion.

Going from 1.2 to 1.3 and from 1.3 to 1.4 caused a fair bit of breakage for quite a few folks.

(which I’ve been steering clear of a little bit, since I think that’s the only part of this discussion that has inherent complexity… 😉)

that is the entire discussion

@noisesmith They had an alpha that rejected those and it broke some very high profile libraries that were widely used -- so they reverted that change.

man I love it when I wildly speculate the truth

semantic versioning relies on clear cut delineation of changes into distinct sets

which is not how changes are

But, yeah, Clojure's stability meant we could go to production on 1.3 alpha 7 or 8 back in 2011 and we could take almost every alpha/beta release since then into production fairly safely.

When I'm updating versions at work, I'm fairly cavalier about patch updates in Clojure libraries and even minor updates in several of them -- but I carefully review even patch updates on Java libraries.

@hiredman sure, but if one assumes we have some semi-mechanistic way of classifying changes into those distinct sets (and yes that’s a HUGE assumption that perhaps we can visit in future discussions!), there’s a different set of questions that I was more interested in for this discussion, namely: 1. is a version label the right place to communicate those different classes of change 2. if not, what would be used instead (and why have version labels at all, in that case - what else are they for, beyond “communicating change”)? 3. if so, is SemVer a good choice of version label format? 4. if it isn’t a good choice, what alternatives are there, and how are they any better?

5. what is the cost of semantic versioning

Agreed - cost needs to be considered for all solutions to this problem (including, but not limited to, SemVer).

a large part o the cost is spent debating which set change falls in to, the other part of the cost is what happens when you assuming you are ok because of semantic versioning and then are not

I think the semver problem shares some of the shape of the problem of writing code. You have two targets, a machine and a human, and bad things happen when their interpretations of what they see disagree. One solution to this is to refine the craft of semantic versioning the same way we refine the craft of writing code. Another solution is to not programmatically evaluate version differences, and make it a human only job. I can see the arguments for both honestly.

FWIW I was product manager on a public REST API some years ago, and one of the first things we did (which, to your point @hiredman was difficult and took months of debate) was to lay out a lengthy set of rules for how we rolled version numbers in that API (and yes, we kept all old versions of the API around “forever”, so that we wouldn’t break clients). We even included numerous concrete examples as a “test” of the ruleset. We used a subset of SemVer for that (just MAJOR.MINOR - “patches” were handled behind the scenes, since this was a cloud service and we decided it was counterproductive to expose that level of detail to API clients).

but like, what if instead of having to have that debate, you just created a new api with every change

What we learned from that exercise is that there is more than one kind of “breakage”, and that what we called “syntactic breakage” was generally trivial to reason about, while “behavioural breakage” was much more complex.

why have major and minor in a web api?

vCOMMITS

@hiredman that’s exactly what we did, but the “name” of the new API was simply the “name” of the old API with the “version component” of that name incremented in predictable ways that communicated something to consumers of the API.

Because we wanted to easily communicate different classes of change to clients of the API (both machine and human, which, as @noisesmith pointed out, is a somewhat fraught game).

And as I mentioned, we had already created (and then published) a tome that explained our reasoning for incrementing MAJOR or MINOR.

i like the idea of a months long debate figuring out what the rules are for changes. but if the clients don't know those rules what's the point? if they don't know when major / minor might change they have to look at all the changes anyways

They knew - we published (a sanitised version of) the doc.

how big was the document?

Not sure if text volume is a food metric for anything, and I’m going from vague memory here (I worked on that product circa 2012, and left that company in early 2016, so it’s all a bit hazy), but my memory is that the sections of the document related to versioning were approximately 1/4 of a ~50 page document. A lot of the versioning material were examples though, which were fairly bulky but low on net-new concepts once the reader became familiar with the patterns.

that sounds brutal

I should also mention that at the end of the months-long debate, we’d basically decided to punt on “behavioural breakage”, and focus our efforts on “syntactic breakage” (which as I mentioned above, is basically trivial).

Once we did that the material mostly fell out in a matter of a week or two.

Product management isn’t for everyone. 😉

I should also mention that for about 3/4 of that time I didn’t have a full time architect assigned to the work, so it did go in fits and starts.

And the architect I eventually got basically believed that backwards compatibility was an illusion, and that clients should basically “suck it up” and deal with whatever we gave them in each new version, so “politics” took some time to work through too.

oh i would like it. but i'm just thinking on being on the receiving end of that. curt dismissals of "not breaking changes, read para 3 of section 3.4.3.2ii ", and then hoping that the people implementing changes read and understand and hold true to that document as much as the consumer

i'm thinking of compiler writers pointing to c standard and writing undefined behavior, we don't care

Right. Little bit less of that behind a REST API, but it can definitely sneak in!

i like the effort though. just wondering about where it could go

For REST APIs, I’m a proponent of the “shy geisha” approach to design btw, to help deal with those kinds of issues incrementally over time.

Basically - reveal as little as you possibly can, and then slowly open up as you get experience / knowledge / battle-testing etc.

I also had the benefit of picking Mike Amundsen’s brain at various conferences etc.

He’s the guru at this stuff.

(and advocates hypermedia in place of versioning, to throw a cat amongst the assembled pigeons 😉 )

while trying to decide on a version scheme for rewrite-cljc, I picked out a few examples I found interesting from Clojure projects https://github.com/lread/rewrite-cljc-playground/blob/master/doc/design/01-merging-rewrite-clj-and-rewrite-cljs.adoc#library-version-scheme-in-progress

oh, do not like meander's scheme

So when you go with a .COMMITS scheme doesn’t that make writing your changelog a bit tricky?

also, so weird that every namespace in meander has the same name epsilon

Another factor worth considering - downstream consumers typically have lots of different upstream dependencies. How does version label fragmentation across those dependencies impose a tax, even though it’s not imposed deliberately by any one of those upstream dependencies?

(another factor in favour of a version labeling standard…)

Obligatory XKCD on the topic: https://xkcd.com/927/

but if everyone has their own understanding of semantic versioning backed by a 50 page document, then does it make it easier to understand changes in your dependencies?

Learn once, apply everywhere has value (to my last point about adoption).

Inventing your own version labeling format has the unintended consequence of worsening fragmentation, and I know which I’d prefer between learning SemVer (or whatever) once and being able to apply that everywhere vs having to learn a new version labeling scheme every single time I want to use a new dependency…

I mean I lived that back in the pre-Maven Java days, and it sucked.

How can you learn once if each dep has a 50 page contract that they may or may not enforce and might be “shy geisha” and decide per instance what a breaking change is

SemVer isn’t 50 pages?

I’m sorry if my REST API example (which also wasn’t 50 pages of versioning documentation) confused the conversation.

And just to agree with one of your points - humans are fallible. But that’s a constant. ;-)