1. 9
  1. 37

    I feel old when reading this.

    A README is a text file that I usually read in less or vim so the fancy badge URLs are just noise.

    I dislike docker with a passion. I think we took the completely wrong route with that technology. It feels like we all said “we give up, let us just repackage everything with every app”. Also, if I share a library as open source, what is the Dockerfile good for?

    No Pull Requests? Of course not. Also no merge-commits for pull requests, ever! Why would I put my own work into pull requests? I am sharing code I wrote, I am not at work.

    One can have automatic builds w/o making them visible on github.

    I really feel like the author has never used anything else but github, which is sad, since there are other ways to do things and they can work equally well.

    1. 3

      I agree. As far as pull requests are concerned, many projects either:

      1. Do development elsewhere but have a github mirror (Could be emails and patches, could be something like gerrit or phabricator).
      2. Allow contributions via multiple methods, including github pull requests.

      In either case, just because a commit hasn’t come in through a github pull request doesn’t mean it hasn’t been reviewed.

    2. 13

      For over 95% of the projects, none of those things are needed, except a README. People use CI/CD and docker for simple projects just to get more experience with the technologies, for when they’ll have a complex project to work on.

      1. 18

        The author may be a bit disingenuous when talking about licenses.

        Feel free to choose one of the most popular:

        • MIT — when you want to give it for free
        • BSD3 — when you want a bit more rights for you
        • Apache 2.0 — when it’s a commercial product

        I strongly believe that choosing a license must be a very informed decision. That the author simply pretends copyleft licenses (notably the GPL) do not exist is worrying, considering that they are in widespread use. Neither does he make any point why the Apache 2.0 license should be chosen over the other liberal licenses “when it’s a commercial product”.

        The choice of license is a one-time act that has legal consequences—if anyone gets their hands on a version under a particular license, it is out there—and must be carefully deliberated at least once in one’s life. Handwaving these concerns away with “(that’s [sic] might be an opinionated list, but whatever)” followed by U+1F609 WINKING FACE does not make it okay.

        1. 4

          Thanks for this. Understanding ramifications of a licensing benefits the ecosystem. People are often unaware of how patent risk, tivoization, “cloudification” and so on can hurt developers and create platform lock-in.

        2. 9

          Disagree on docker as well. Might be nice for a few people but I don’t use it for development and will probably not use it for deployment, so why should I waste time? (Yes, I am just now wasting time working with docker…)

          Patches welcome, as they say - I surely won’t turn down a PR if someone offered a Dockerfile for a project I work on.

          1. 9

            No Dockerfile and Bloated dependencies? I thought that one contradicts the other, no?

            1. 4

              Docker would be a huge dependency, but this article isn’t arguing that you should depend on Docker. The article is arguing for adding a Dockerfile to make it easier for people to run your project in docker, but unless it’s actually necessary, your project absolutely shouldn’t depend on it.

              1. 1

                Why so? I don’t get it, can you clarify a bit more?

                1. 1

                  I’d like Chrome, so …

                  http://dockerfile.github.io/#/chrome -> http://dockerfile.github.io/#/ubuntu-desktop -> http://dockerfile.github.io/#/ubuntu -> https://hub.docker.com/_/ubuntu … but first, I need a Linux VM to run Docker on it! Doesn’t that look bloated to you? Did I miss anything?

                  1. 2

                    Sorry, are you counting the Linux kernel as bloat because you want to use a technology your operating system’s kernel doesn’t support?

                    I agree that Docker is not the leanest piece of tech out there but that seems drastically unfair.

              2. 8

                Nice summary of a good README, one thing I’d add that really grinds my gears is projects not taking the time to add at least a single sentence explaining what the thing actually does, in a way that people that may not even be involved in the ecosystem at all can understand what problem they are trying to solve.

                What most have is something along the lines of “Do what x does but with y”, with both blanks being libraries or concepts people not involved in eg. Kubernetes, OpenStack or the newest JavaScript stuff would maybe know by another name or which might be completely made up.

                I try to do this with all my projects, just adding a succinct description I would tell eg. my parents as well as two usage examples does wonders for clarity, in my opinion.

                Examples (shameless plug): https://github.com/cbdevnet/midimonster

                1. 1

                  Nice repo and great README, thank for sharing!

                2. 5

                  Docker is overkill for some projects, and it also depends on what’s your app doing. If it’s a server that needs Nginx, Python and Postgres, then sure Docker is a right solution. But if it’s just a command line tool written in Node or Go, npm i or go get is much simpler.

                  1. 4

                    I always say this, but a “readable README” is always preferable over a “README that says something” … but only when opened via GitHub.

                    Badges are just among the things that have become so annoying in my experience, it makes opening a README via text editor nearly unreadable. Others are long lines, inline links, HTML, images after images.

                    The author’s README is ok, but certainly not my favourite style…

                    1. 3

                      I’d love to see standard machine-parsable metadata on projects:

                      • Maturity: alpha/beta/stable/mature/finished/abandoned
                      • Stability: minimum guaranteed time between deprecation and subsequent breaking change
                      • is semver used?
                      • Security: contact points for notifications, policy around backporting fixes into stable releases
                      • PR and contributions policy
                      1. 1

                        s/semver/a versioning scheme that matches community expectations/
                        I am not calling semver insensible.

                        The Haskell world uses the Package Versioning Policy.

                      2. 3

                        When you’re doing a pull request, some random guru-senior-architect might occasionally check your code and suggest few changes. Sounds unlikely but any additional eyes might uncover bugs or architecture mistakes.

                        Is this true? I would love to have someone review my code but I cant see it ever happening. Do I just open a PR and hope someone comes along to review it? How would they even know I am waiting for public review. It feels quite rude to jump in to someone elses project and start reviewing their changes.

                        1. 4

                          “Watchers” of the repo will get notifications, so they can get involved pretty easily if they want to. Also, you can add a label like “needs review” or something like that to attract more attention.

                        2. 1

                          On having bloated dependencies, badly formatted code and no git tags? Absolutely agreed. Those are all bad signs. I’m sceptical about the rest.

                          There are a lot of bad READMEs out there no doubt. But the suggestion that you should fill your README with badges instead of it being a proper README with nicely formatted text I can read in a text editor is juvenile.

                          Licenses? What if I don’t actually care about some stupid company using my code? I’d rather they didn’t, actually, so I use Artistic License 2.0 or AGPLv3. The presumption that people writing and publishing free software are keen to have some company make money on their work is strange to me.

                          It’s up to you to write yourself a Dockerfile for your projects, not me. I don’t use Docker.

                          GitHub pull requests are a horrible way of managing software changes that ruin commit history and create a huge amount of noise in changes. They make it virtually impossible for anyone other than the original pull requester to change the code in the pull request without recreating the whole pull request. They’re just.. bad.

                          Tests, automated builds, etc. are not necessary at all.