Next release

[Anton-Latukha]

0.9.1 is out.

Now we can gather information here.

[sjakobi]

@Anton-Latukha Would you mind allowing a bit more time for review with the next releases?

Between your last changelog edits in https://github.com/haskell-nix/hnix/pull/674 and the 0.9.1 release tag, not even 3 hours had passed! Allowing 48 or at least 24 hours for these reviews would seem more reasonable to me.

[Anton-Latukha]

Well. You keep wanting to review docs - and I keep saying - just edit them however you want, just as Wikipedia - it is not a code.

The main idea of edit is that Sorki contributed a changelog. but he did not looked/followed the esteblished structure of the changelog, its previous entry, and so information was contributed uncategorized, and entries sometimes were not very informative or at all could be reduced (like "docs added/updated for..." and "dependencies were removed" - it is news that seem good for us - but user does not interested in spamming them with those, they need more effective to the point structure and technical entries). So I put categorization that shows that all changes are additional by nature removed "added/updated docs..." and put additional info on deps, since repline boundary is important news.

The most important thing in text - is that new edition introduce edits, and that we put needed stuff, that user needs to know, into the changelog, the review of text is not important. We also always can reupload the changelog. You always can make a review by editing the text.

With your approach to texts - you would've been ideal editor in chief for a very serious journal, but also does not overstress it, you can not review all the editions of text, and of course, that would be a waste of your Haskell possibilities.

You can edit them right now - I would not even flinch, since I trust you and your professionalism.

The changelog is our daily newspaper of news, we informed users on news important for them, tomorrow - it would be a paper or at best - belong to the archive dust corner as old history. Even now - since it is 0.9.1 - probably most people would not even notice or read the changelog - update would just implicitly autoroll for them. We have much more effective and important stuff - making the future arrive.

[sjakobi]

Maybe I shouldn't care about changelogs as much, but I do! :) So I would just appreciate having the chance to look them over before they are released. If that's not an option for you, I wouldn't mind writing the changelogs myself, either!

In the case of 0.9.1, your edit to mark things as "additional" actually highlighted that the change in the nixVersion wasn't an addition at all! I wanted to point that out, but it was already too late.

[Anton-Latukha]

Well, if somebody does not uses Nixpkgs (which is pretty unique case for Nix interpreter), but uses fully custom code and store repository, and uses HNix on top of that, and so had some Nix 2.0 compliant code - then yes - that may be a problem for them. But as you say to me often - there were no bug reports from downstream so why bother with something if nobody in downstream reported on it.

On the other side of the question. Well, nixVersion "compliance" set just because Nixpkgs requires it so, just because for Nixpkgs evaluation that setting is mandatory, we, in reality, do not even know, did not made assessment, or from my point of view currently do not even have enough ground to make any sort of statement do we comply or not (as we know data type system does not comply to language strictness requirements), so in fact, - that is a cosmetic change, we had not changed the API.

If we nixVersion comply and changed API - that would be a major version release.

But since we pretend we just complied with 2.3 already - nixVersion change is cosmetic change, there is no API changes and so it is additional.

Of course we can put statement that we return new API version complience 2.3 so it technically changes that API behaviour, so we may optionally bumped the major version, but it is very much placebo major version then, since there is no real Haskell API changes, during release process, we all seemed to agree it is 0.9.1 and there were no breaking changes, so that is on what decision is based.

Personally, I used to read too much IT news in my life for a number of years, on top of it I even read RSS feeds and had Changelog application installed on the mobile phone to spam myself with "technical info", so I had read enough to be sure that too much information is not effective. Now I love tiny terse to the point changelogs, as we discussed - following PVP and that is all.

Even the dependency bounds - most changelogs do not mention those.

---

Upper bumps - no reason to mention.

1. Only particularly the Haskell subset of Nixpkgs works completely other way around from all other stores - the Haskell subset of Nixpkgs rolls-out updates even when they are broken. Because what Peti tries to do is to keep a direct synced-up mirror of current Hackage inside Nixpkgs. And since nevertheless despite of agenda to mirror Hackage - Nixpkgs tries to dodge the progress and freezes old versions and creates new package versions on the side - the projects have no way of knowing or tracking that process (except make internal testing). And so ship crashes on the Nixpkgs cliffs Nixpkgs not put on the map, so we may notify Nixpkgs maintainers in Changelog that we are heading in the course, and they can check is upper bound cliff was put by them in the store. But as maralorn put it - that is not our responsibility, project works for bleeding-edge best versions from Hackage, Nixpkgs strives to be the mirror of Hackage, so we should not care that Nixpkgs downstream breaks Nixpkgs downstream. We can post upper bounds for the Haskell subset specifically for only Nixpkgs, but since the Haskell subset updates of Nixpkgs is an automatic process that happens daily - nobody ever reads the Changelogs before breackage arrives on the cliff, and when breakage happens - people start from the shipwreck, comparing to previous build and debuging deps. Only several language subsets in Nixpkgs have that property (and maybe AUR, and some Gentoo ebuilds which are not official store), even Nixpkgs itself, and all other stores, work the other way around and do not roll-out without tests and stores do not release packages with unmet dependencies, it is the sole reason of the store - consistency of package deliverance.
2. If the store (any store) has never version - it would use it, if it does not - it would use the previous version. So why we post upper bounds then?

So upper bumps - no reason to mention.

---

Lower bounds - no testing proof to mention.

1. Project maintainers do not actively maintain and test the lower bounds, we do not even know does project really complies because Cabal automatically picks more up to date versions for everybody.

2. If Cabal had an option to reverse the coercion, and so had an option to pick "the worst versions" for the project compilation - that seems like a good test, but there is no option in Cabal, probably because everyone cares and chooses to use new and best versions.

3. Again, software stores update packages only when the project builds and tests and when its deps are met by the store. There is no way to update world of software manually, so all stores also have automated systems. And those automated systems permit a release only when Cabal solved the deps and build & test processes passed - so that means the software store supports the project dependencies - so they do not need our upper no lower bounds dependency info, since they automatically test themself for consistency. I also think even Gentoo store rolls automatically and maintainers do not read all changelogs of all tens of thousands of projects all the time, they read-only when the package does not pass.

What the conclusion I draw from my ramble:

1. Haskell Changelog main existence is for programmed automation that works on it, readers are the people whose projects programmatically depend on the library, they comply with our major releases and so interested only in PVP info.

2. Again - it would be somewhat good if we test for project lower bounds (since we already test for upper), but until https://github.com/haskell/cabal/issues/2876 solved - we can not bother ourselves with it.

3. Stores, they only package the project, they do not care about internal project affairs or API changes. Stores by their purpose already themself and automatically, using metadata version from the Cabal file, without people overlook - check for the consistency of packages and dependencies. Until someday comes around to debug why the build fails, and Cabal/their store automation produces pretty clear messages of unmet dependency. So Changelog does not prevent the release to store going smoothly, using the Cabal bounds the automatic build fails in the store happens and so release to store does not happen. Store maintainers do not read the changelogs for version bounds info, version bound notification arrives to them before they ever, if they ever think of reading the changelog, the people from 1 read the changelogs for interface compliance.

Also as a maintainer in Nixpkgs, I read the changelogs only if automatic update build/tests did not pass and only of major releases, and often.

The inclusion of info that project switched to the mandatory new incompatible version of the library is beneficial, since it essentially can be seen as theoretically equivalent to switching (migration) to the new dependency (both lower and upper bound change at the same time, and they do not overlap with previous bound requirements at all, lower bound becomes current version, and upper bound still does not exist), then extending support to the newer versions, shortening of older versions. In other words - it is a corner case that is equivalent to migration to incompatible version - that is why it must be mentioned.

Because other maintainers would prefer terse to the point changelogs then long papyruses, for example, peti actively complained that pandoc changelogs are so huge and unparsable for essential information: https://pandoc.org/changelog.txt (notice - first are minor release changelogs), so he just ignores them. I am not talking about the person, I am talking that maintainers do lazy to the point technical process and skip reading changelogs, especially if it hides important for them info in other info.

Myself, as I think everyone, currently learning what requires to be in the changelog, and what is not, from release to release we get better at this.

If someone particularly would take responsibility of forming a changelog - that can save in volume of mutual discussions on changelog evolution - then I would ask to formulate and keep particular rules that hold strong reasoning what information should be passed into changelog and which is not, so the rules would be able to fluctuate and be addressed. I myself love that the process evolves, we patch it, it gets better and we discuss it, and I love that we simply keep rules inside changelog content and its form itself, and think we should be concerned only with the major release changelogs.

[sjakobi]

@Anton-Latukha That's a very long comment! :)

Could you possibly make a short TLDR-style summary?

I had also assumed that my request for review time would be fairly uncontroversial. I'd rather not have an extended discussion about it.

[Anton-Latukha]

Well, I have a definite sin being prolific in writing and talking argumentation, it is a thinking vehicle, I try to make reasoning clear.

---

In summary.

Release code was essentially done by sorki. He contributed Changelog on his own work. You reviewed and confirmed the changelog. I came in and saw some obvious things for me, that changelog was not following any structure, that the major and minor changes need to be always explicitly denoted, in that way the changelog is easier to parse and understand for people.

Since he wrote the code and the Changelog, you reviewed and approved it, a bit of time went and nobody merged it. I decided that you both are satisfied with the result, so I merged it, then added the structuring and reformulated words a bit in it. Waited a bit, and decided that everything is done to published it.

We all three reviewed the changelog. I do not want to send every plaintext reduction through scientific peer review, since it explodes the numbers of messages and steps.

---

And everybody can fix the changelog afterward, and we can release x.x.x.x+1 for it.

---

There should be some line between when we do peer review, and when we have a belief and see obvious action and trust one another, otherwise, we would stagger from internal analysis paralysis and mutual peer review analysis paralysis.

[sjakobi]

@Anton-Latukha I feel that by rewriting the changelog after the release PR, you voided our agreement on what the release looks like. To me, the changelog is a very important part of the release.

I would strongly prefer that we try to reach an agreement on the release details and then publish the release with exactly these details.

If you don't like other people reviewing your changelogs, then please leave writing the changelog to someone else.

[sjakobi]

Regarding the next release, I'd like to cut it once https://github.com/haskell-nix/hnix/pull/686 is done, so we can unblock https://github.com/commercialhaskell/stackage/issues/5558 and https://github.com/commercialhaskell/stackage/issues/5535.

[Anton-Latukha]

Look, sorki submitted text, you edited text and approved it, I edited text and approved it, we released it. Because text was reviewed and approved by all 3 people - it got released. Even in scientific papers, once paper gets approval review from a peer, further edits of other peers to the paper do not need the approval of everyone prior people, it is not like 10 people sit and collectively veto every edit - then it would be multiple-fold more effort and most of edits would be vetoed and paper would never would get ready and never would get published.

---

If you don't like other people reviewing your changelogs, then please leave writing the changelog to someone else.

I even more open then you for the process, reviewers can get my text edit it without regard to me, since the groundwork is accepted and done - I trust them improving on it.

What we have - is the arguing that I apply this open editing principle to others also, I decide to not bother people and to not block their contribution and to not force them to self-edit it to my liking, I merge their contribution and add my edits on top of it.

Documentation and programming logic are very different for the projects.

This is how Wikis work, otherwise documentation would not work, it would be painful and we would argue about it all the time.

What I am up for, is that you can take charge of result text information, but I would ask to accept my doc contributions openly, and then I trust people (and you also) to edit documentation to your liking.

[sjakobi]

What I am up for, is that you can take charge of result text information, but I would ask to accept my doc contributions openly, and then I trust people (and you also) to edit documentation to your liking.

I find it difficult to agree to this in general. Ultimately, I believe that documentation is about as important as code. Good (relevant, understandable) documentation can be very valuable – bad (incorrect, incomprehensible) documentation can be a problem. I believe that reviewing documentation changes is rather important because documentation issues can't be caught by the type-checks and tests that we have for code.

My suggestion is that we try to figure out a process for documentation improvements that works for all of us while that work is happening.

[Anton-Latukha]

Closed documentation is almost never of good quality.

If the edits is hard to get in - the edits do not get in, and so the useful info for the huge number of users, and fixes do not get-in, on the grounds that people do not agree on 1-3% words chosen in the PR, which due to nature, looseness and breadth language is always the case.

I have too much examples when maintainers do not accept 98% useful info, great PR, due to their stinginess to police the speech in 2% of the content of the PR: Last one is in: https://github.com/alphapapa/org-protocol-capture-html/pulls?q=is%3Apr

PRs with useful edits were done and submitted, and waited 1.5 years to be merged, discussions started. The maintainer disagreed on the word choice:

Why did you change Bookmarklet to Browser-side script?

Which essentially means that he is in power and does not like that the some particular words contributed, which in fact are the more precise proper term use. Is that bookmarklet word properly used for javascript:// type URLs - no, is that one section name change right - yep, - is a big deal, no, but maintainer did it a big deal. Because maintainer blocks whole PR and makes it a big deal for PR. On the merit of one word use all doc improvements are not accepted. And on top of it contributor has 3 choices:

1. Follow the started by maintainer discussion. Present in-depth historical, etymological, semantical, and definition research and assemble all proofs to justify the word choice. Making honest work in reserch&proofs for discussion contributor invests (~5x) times more effort into PR, meanwhile that may mean nothing since by presenting objective proofs the risk of it all being rejected and that even maintainer can take term use to the personal level and passively decide to get offended. For example, this is what happened there in #34, where all PR and other awaiting doc PRs got tanked because of the explanation that bookmarklet is a portmanteau term of bookmark and applet and it regards to browser bookmarks and not to JavaScript URL, the term even everyone forgot what it means.
2. Maintainer asks the contributor to self-censor speech, contributor abides, and self-censors words. Since contributor silently abided - the maintainer thinks that he did a good job of maintaining the project developed by humans & the community. Contributor feels less and less motivated with every PR presented.
3. Contributor provides big additions to docs in PR. Maintainer polices the word choice and contributor sooner than later abandons the PR. Maintainer decides that contributor not corrected the PR, so self-justifies that never merging it is a right action, while contributor sees that he brought useful documentation for users of the project and that is the main value of the PR, contributor does not understand why maintainer forces him to do the word edits maintainer wants, when maintainer has all possibilities in 5 seconds to get text into the form he wants. To get obviously useful human text merged, contributor decides it is too much debate and effort to make maintainer accept obvious improvements, so abandons the PR, and learns to not contribute to the project further. For example in org-protocol-capture-html it took me 3 major doc PRs and 1.5 years to become sure that improvements are unmergable because maintainer treats English doc PRs as code PRs and does not accept the reason why they do not get merged.

The truth is - there were instructions, platforms, and use cases covered in PRs. Improvements did not get accepted (which seems to be the main agenda of the maintainer - to merge improvements) and maintainer destroyed relationships with contributor for the single word in the docs, trying to force it, when he could've by himself change wording in 5-second edit.

[Anton-Latukha]

To prove the point that doc contribution should be an open democratic process. And not authoritarian review and burdening contributor with self-censoring.

The maintainer can nitpick the two-lines of text in https://github.com/haskell-nix/hnix/pull/689 to the point of oblivion.

Closed doc model depends on everyone being too adequate and too healthily constantly giving a pass. It is a very fragile model. If someone with veto does not currently have any of: time, qualities, mood, emotional state - PR would not get in, in wall of text there is always would be a nitpick to rebuff contributor work and contribution.

The open doc model does not depend on people's qualities, mood, emotional state - it depends on open evolution of meaning,

[Anton-Latukha]

Even the on-line doc editing is an open process, people most often just straightly change the text, or make edits, with the ability of an editor to review them and roll-back/edit them post factum, that model is much more open then authoritative maintainer PR code review.

For example, to show that the authoritative process for human language works poorly, I would make my suggestions in https://github.com/haskell-nix/hnix/issues/675. Essentially what maintainer review of PR does is vetoes the PR and makes you work until you edit your text the way maintainer wants to edit the text.

And since word choice is indeed debatable - the review would never terminate because all debates geometrically spawn non-terminating discussions.

[Anton-Latukha]

I believe that reviewing documentation changes is rather important because documentation issues can't be caught by the type-checks and tests that we have for code.

It is a job of maintainer to review the PRs.

Maintainer reviews the docs before the merge.

He reads through, and if it looks fine, or if the maintainer has some nitpicks that bother him - that is not the reason to start the discussion and bother the contributor - maintainer can himself write in English.

The review od docs does not mean that the maintainer should force the contributor to rewrite the submitted docs, since one who has the idea how docs should be edited - should edit docs himself.

[Anton-Latukha]

I suggested, if you want to be a Chief Editor of the project - I am Ok with it, I would request to accept my docs, not spawn discussions, and I trust you making edits.

Since I plan to submit a bunch of docs I think we should arrive at the middle ground on this question.

If you want it so much - I am Ok with having rigorous peer-review of docs, as I already have shown my points and you would understand both the shortcomings of this paradigm for documentation. If the approach would not work for me or other contributors - me/they can contribute code and not docs, as project and people often accustomed doing it this way.

[Anton-Latukha]

Also, the middle ground may be - do not ask to rewrite minor things, but create a commit with edits in a PR, or edit after merging, former essentially turns PRs into the online distributed cross-edit word processor.

[Anton-Latukha]

0.10.0 is out.

Next thread: #714