1.  

    Maybe a dumb questions, but in semver what is the point of the third digit? A change is either backwards compatible, or it is not. To me that means only the first two digits do anything useful? What am I missing?

    It seems like the openbsd libc is versioned as major.minor for the same reason.

    1. 9

      Minor version is backwards compatible. Patch level is both forwards and backwards compatible.

      1.  

        Thanks! I somehow didn’t know this for years until I wrote a blog post airing my ignorance.

      2.  

        PATCH version when you make backwards-compatible bug fixes See: https://semver.org

        1.  

          I still don’t understand what the purpose of the PATCH version is? If minor versions are backwards compatible, what is the point of adding a third version number?

          1.  

            They want a difference between new functionality (that doesn’t break anything) and a bug fix.

            I.e. if it was only X.Y, then when you add a new function, but don’t break anything.. do you change Y or do you change X? If you change X, then you are saying I broke stuff, so clearly changing X for a new feature is a bad idea. So you change Y, but if you look at just the Y change, you don’t know if it was a bug-fix, or if it was some new function/feature they added. You have to go read the changelog/release notes, etc. to find out.

            with the 3 levels, you know if a new feature was added or if it was only a bug fix.

            Clearly just X.Y is enough. But the semver people clearly wanted that differentiation, they wanted to be able to , by looking only at the version #, know if there was a new feature added or not.

            1.  

              To show that there was any change at all.

              Imagine you don’t use sha1’s or git, this would show that there was a new release.

              1.  

                But why can’t you just increment the minor version in that case? a bug fix is also backwards compatible.

                1. 5

                  Imagine you have authored a library, and have released two versions of it, 1.2.0 and 1.3.0. You find out there’s a security vulnerability. What do you do?

                  You could release 1.4.0 to fix it. But, maybe you haven’t finished what you planned to be in 1.4.0 yet. Maybe that’s acceptable, maybe not.

                  Some users using 1.2.0 may want the security fix, but also do not want to upgrade to 1.3.0 yet for various reasons. Maybe they only upgrade so often. Maybe they have another library that requires 1.2.0 explicitly, through poor constraints or for some other reason.

                  In this scenario, releasing a 1.2.1 and a 1.3.1, containing the fixes for each release, is an option.

                  1.  

                    It sort of makes sense but if minor versions were truly backwards compatible I can’t see a reason why you would ever want to hold back. Minor and patch seem to me to be the concept just one has a higher risk level.

                    1.  

                      Perhaps a better definition is library minor version changes may expose functionality to end users you did not intend as an application author.

                      1.  

                        I think it’s exactly a risk management decision. More change means more risk, even if it was intended to be benign.

                        1.  

                          Without the patch version it makes it much harder to plan future versions and the features included in those versions. For example, if I define a milestone saying that 1.4.0 will have new feature X, but I have to put a bug fix release out for 1.3.0, it makes more sense that the bug fix is 1.3.1 rather than 1.4.0 so I can continue to refer to the planned version as 1.4.0 and don’t have to change everything which refers to that version.

                2.  

                  I remember seeing a talk by Rich Hickey where he criticized the use of semantic versioning as fundamentally flawed. I don’t remember his exact arguments, but have sem ver proponents grappled effectively with them? Should the Go team be wary of adopting sem ver? Have they considered alternatives?

                  1.  

                    I didn’t watch the talk yet, but my understanding of his argument was “never break backwards compatibility.” This is basically the same as new major versions, but instead requiring you to give a new name for a new major version. I don’t inherently disagree, but it doesn’t really seem like some grand deathblow to the idea of semver to me.

              1. 8

                Regarding Table of Contents generation, what do you think about hxtoc(1) which is part of the HTML/XML utilities by the w3c?

                Also, I’ve made a similar experience regarding a joyful discovery of CommonMark recently, but instead of using the parser you mention, I’ve taken up lowdown as my client of choice. I guess this is something it has in common with most C implementations of markdown, but especially when compared to pandoc, it was fast. It took me a fraction on a second to generate a website, instead of a dozen or more. So I guess, I wanted to see, what other clients you’ve looked into, for example discount, as an example of an another popular implementation.

                1. 5

                  Hm, I’ve actually never heard of hxtoc, lowdown, or discount!

                  I haven’t been using Markdown regularly for very long. I started it using more when I started the Oil blog in late 2016. Before that, I wrote a few longer documents in plain HTML, and some in Markdown.

                  I had heard of pandoc, but never used it. I guess cmark was a natural fit for me because I was using markdown.pl in a bunch of shell scripts. So cmark pretty much drops right in. I know a lot of people use framework-ish static site generators, which include markdown. But I really only need markdown, since all the other functionality on my site is written with custom scripts.

                  So I didn’t really do much research! I just felt that markdown.pl was “old and smelly” and I didn’t want to be a hypocrite :-) A pile of shell scripts is pretty unhygienic and potentially buggy, but that is what I aim to fix with Oil :)

                  That said, a lot of the tools you mention do look like the follow the Unix philosophy, which is nice. I would like to hear more about those types of tools, so feel free to post them to lobste.rs :) Maybe I don’t hear about them because I’m not a BSD user?

                  1. 4

                    I had heard of pandoc, but never used it.

                    It’s a nice tool, and not only for working with Markdown, but tons of other formats too. But Markdown is kind of it’s focus… If you look at it’s manual, you’ll find that it can be very finely tuned to match ones preferences (such as enabling or disabling raw HTML, syntax highlighting, math support, BibLaTeX citations, special list and table formats, etc.). It even has output options that make it resemble other implementations like PHP Markdown Extra, GitHub-Flavored Markdown, MultiMarkdown and also markdown.pl! Furthermore, it’s written by John MacFarlane, who is one of the guys behind CommonMark itself. In fact if you look at the cmark contributers, he seems to be the most active maintainer.

                    I usually use pandoc to generate .epub files or to quickly generate a PDF document (version 2.0 supports multiple backends, besides LaTeX, such as troff/pdfroff and a few html2pdf engines). But as I’ve mentioned, it’s a bit slow, so I tend to not use it for simpler texts, like when I have to generate a static website.

                    I know a lot of people use framework-ish static site generators, which include markdown.

                    Yeah, pesonally I use zodiac which uses AWK and a few shell script wrappers. You get to choose the converter, which pipes some format it, and HTML out. It’s not ideal, but other than writing my own framework, it’s quite ok.

                    Maybe I don’t hear about them because I’m not a BSD user?

                    Nor am I, at least not most of the time. I learned about those HTML/XML utilities because someone mentioned them here on lobste.rs, and I was supprised to see how powerful they are, but just how seemingly nobody knows about them. hxselect to query specific elements in a CSS-fashion, hxclean as an automatic HTML corrector, hxpipe/hxunpipe converts (and reconverts) HTML/XML to a format that can be more easily parsed by AWK/perl scripts – certainly not useless or niche tools.

                    But I do have to admit that a BSD user influenced me on adopting lowdown, and since it fits my use-case, I stick by it. Nevertheless, I might take a look at cmark, since it seems interesting.

                  2. 2

                    Unfortunately, it looks like lowdown is a fork of hoedown which is a fork of sundown which was originally based on the markdown.pl implementation (with some optional extensions), and is most likely not CommonMark compliant. Pandoc is nice because it can convert between different formats, but it also has quite a few inconsistencies.

                    One of the biggest reasons I like CommonMark is because it aims to be an extremely solid, consistent standard that makes markdown more sane. It would be nice to see more websites move towards CommonMark, but that’s probably a long shot.

                    Definitely check out babelmark if you get a chance which lets you test different markdown inputs against a bunch of different parsers. There are a bunch of example divergences on the babelmark FAQ. The sheer variety of outputs for some simple inputs is precisely why CommonMark is useful as a standard.

                    1. 3

                      Lowdown isn’t CommonMark conformant, although it has some bits in place. The spec for CommonMark is huge.

                      If you’re a C hacker, it’s easy to dig into the source to add conformancy bit by bit. See the parser in document.c and look for LOWDOWN_COMMONMARK to see where bits are already in place. The original sundown/hoedown parser has been considerably simplified in lowdown, so it’s much easier to get involved. I’d be thrilled to have somebody contribute more there!

                      In the immediate future, my biggest interest is in going an LCS implementation into the lowdown-diff algorithm. Right now it’s pretty ad hoc.

                      (Edit: I’m the author of lowdown.)

                      1. 2

                        One of the biggest reasons I like CommonMark is because it aims to be an extremely solid, consistent standard that makes markdown more sane. It would be nice to see more websites move towards CommonMark, but that’s probably a long shot.

                        I guess I can agree with you when it comes to websites like Stackoverflow, Github and Lobsters having Markdown formatting for comments and other text inputs, but I really don’t see the priority when it comes to using a not 100% CommonMark compliant tool for your own static blog generator. I mean, it’s nice, no doubt, as long as you don’t intentionally use uncertain constructs and don’t over-format your texts to make them more complicated than they have to be, I guess that most markdown implementations are find in this regard – speed on the other hand, is a different question.

                        1. 1

                          Are you saying that CommonMark should be used for comments on websites, but not for your own blog?

                          I would say the opposite. For short comments, the ambiguity in Markdown doesn’t seem to be a huge problem, and I am somewhat comfortable with just editing “until it works”. I don’t use very many constructs anyway – links, bold, bullet points, code, and block code are about it.

                          But blogs are longer documents, and I think they have more lasting value than most Reddit comments. So although it probably wasn’t strictly necessary to switch to cmark, I like having my blog in a format with multiple implementations and a spec.

                          1. 3

                            At least in my opinion, its useful everywhere, but more so for comments, because it removes differences in implementations. Often times the people using a static site generator are developers and can at least understand differences between implementations.

                            That being said, I lost count of how many bugs at Bitbucket were filed against the markdown parser because the library used resolves differences by following what markdown.pl does. I still remember differences in bbcode parsing between different forums - moving to a better standard format like markdown has been a step in the right direction… I think CommonMark is the next step in the right direction.

                            1. 1

                              The point has already been brought up, but I just want to stress it again. You will probably have a feeling for how your markup parser works anyway, and you will write according. If your parser is commonmark compliant, that’s nice, but really isn’t the crucial point.

                              On the other hand, especially if one likes to write longer comments, and uses a bit more than the basic markdown constructs on websites, having a standar to rely on does seem to me to offer an advantage, since you don’t necessary know what parser is running in the background. And if you don’t really use markdown, it doesn’t harm you after all.

                      1. 3

                        The duotone themes for atom do something similar to this. They aim to use the main colors for more important portions and muted colors for less important things, like builtins, etc.

                        I’ve also experimented with this a little bit with https://github.com/belak/emacs-grayscale-theme. Unfortunately, the theming in emacs isn’t quite as flexible as atom, so it’s a bit limited.

                        1. 1

                          The workspaces idea is really interesting… it would be cool to see some sort of experimental interface built around it - use a single object store and somehow ensure that proper access controls are in place. I’ve played around with implementing a custom git-receive-pack and git-upload-pack using libgit2, but it’s a pretty large pain (or at least it was a year ago).

                          One thing worth noting: at least for the storage portion, GitHub almost definitely does something similar to this. If you ever push a commit to a fork, you can access that commit through a URL in the main repo. My guess is that they specifically push the forking model so they can save on storage.

                          As an example, you can take a look at these commits:

                          1. 13

                            Their main website (at least as far as I know) is still at https://geany.org/.

                            It does seem odd to me that the .sexy domain is being used for any text editors.

                            See also:

                            1. 8

                              Still cringey IMO

                              1. 2

                                I always thought the vim.sexy was more of a parody/satire of that style of site from a fan of the editor more than anything else.

                              1. 3

                                Bolt is a super useful, simple data store. I’ve written a small wrapper around it called nut to make it simple to store objects (by marshaling them to json, but it may make more sense to store them as gobs or protobufs in the future) rather than just bytes. It’s pretty experimental, but I’ve been using it in personal projects for a while.

                                https://github.com/belak/nut/

                                Also, bolt isn’t really being updated any more, but it’s still considered fairly stable. There’s a coreos fork called bbolt which aims to keep updating it.

                                1. 1

                                  It is also worth mentioning that https://github.com/asdine/storm exists, and does JSON, gob and protobuf encoding. It also gives you a KV string store that handles the copying of bytes.

                                1. 3

                                  But Zsh does have a visual mode! Don’t rebind v to something else. Pick something else: I use ‘^X^E’.

                                  I’ve seen this bind v to edit-command-line advice before, probably because oh-my-zsh does it. I can only guess that the existence of visual mode simply isn’t obvious because by default it is highlighted in a manner that is indistinguishable from the cursor. My advice is to pick something more obvious and set it in zle_hightlight. Note that much of the zsh documentation talks about the “region” which is emacs terminology.

                                  1. 2

                                    Does Zsh have a visual mode? If so it’s not on by default, or at least by default it’s not mapped to v in command mode. I also could not find any documentation on Zshell visual mode. Can you provide links to any documentation or articles on this? Closest thing I found was a Zshell plugin that implemented this behavior (https://github.com/b4b4r07/zsh-vimode-visual).

                                    1. 2

                                      Go to http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html or type man zshzle and search for the word “visual”. There are several references. The feature was added three years ago. In general for vi-mode I would recommend using at least 5.0.8 and preferably 5.1 or newer as a lot of vi/vim related improvements were made around the time of those releases. To verify, run zsh -f and try bindkey -a v and you should find v is bound to visual-mode. There’s also visual-line-mode for V and a visual keymap.

                                      1. 1

                                        Wow! How did I miss that?! That’s really nice, and much faster than opening Vim. I will remove my custom mapping and update the blog post accordingly.

                                      2. 1
                                        1. 1

                                          I actually decided against using that vi plugin for some other reasons, so at least in theory v should be mapped to the default command.

                                    1. 1

                                      We’ve got a few additional hacks in prezto you might be interested in: https://github.com/sorin-ionescu/prezto/blob/master/modules/editor/init.zsh

                                      I don’t personally use it, but one of our regular contributors has submitted multiple improvements and if you have any other ideas, we’d love to hear them!

                                      1. 1

                                        Thanks! I’ll comb through it and see if I can find any other gems. I’m still pretty new to Vi mode so this blog posts pretty much sums up what I’ve learned so far.