1. 46

  2. 21

    Agree and disagree. Does your readme say “here’s a thing. maybe it works.”? That’s ok.

    Does it say “my new whizbang framework kicks the pants off everything else because it’s been meticulously hand crafted for awesome!”? And it’s still shitty? That’s not ok.

    1. 25

      I thought I’d post my standard readme, btw. :) I’m particularly proud of the “except for the parts that aren’t” wording.

      Experimental Code

      This source-code repository is published here in the hope that it will be useful or at least interesting, but is very likely to be in an unfinished state, and not necessarily a consistent one, either.

      The sole representation is that (except for the parts that aren’t), this code is authored by me - Irene Knapp.

      If the repository contains information about its own licensing, that information is normative; otherwise, all rights are reserved and it is provided for information only.

      If you do something that requires me to write a better disclaimer, I will be very irate.

      1. 7

        Ha, very nice. I’m considering borrowing just this part in mine:

        Disclaimer: If you do something that requires me to write a better disclaimer, I will be very irate.

        1. 1

          You have my blessing. :)

        2. 3

          That’s a great idea and one I will be stealing promptly! Thanks for sharing.

          1. 1

            If you do something that requires me to write a better disclaimer, I will be very Irene.
            Fixed it for you :)
            What about “I will be a very irate Irene”?

            1. 2

              Oy. :) That was awful, although I suppose I set myself up for it!

          2. 6

            I feel like “hand crafted for awesome” is a promise that the code will be a psychedelic experience, which is pretty much the opposite of a promise that it adheres to principles of quality engineering. :)

            1. 1

              Reminds me of a JS lib I saw advertised as “agonizingly beautiful”. Because “agony” is the feeling you want associated with your software! :)

            2. 3

              Here’s a thing, maybe it works: https://github.com/choongng/objc-tidy

              I posted it earlier but in my exuberant rebasing I accidentally deleted the source (now fixed). The thing that would make me happiest is if someone put this functionality into clang-format but in the mean time if you have an Objective C codebase the combination of the two can help tidy things up.

            3. 9

              There is no obligation to free labour. Every hour you put in working on your project for free is a gift to the world. If the world comes back to you and says “You are a bad person for not supporting this thing I need you to support” then fuck them. If they want that they should pay you for it, or do it themselves.

              Well, yes, but I would argue that below a certain threshold of quality, you should really consider whether it is worth publishing (or at least promoting) your library at all. There is such a thing as a library that is so shitty (or, more likely, so incomplete) that it costs its users more time than it saves them. If you must release such a library, I think you have an obligation to make the state of the library pretty clear upfront.

              I’ve wasted a lot of time dealing with libraries that purport to implement some spec or protocol, only to find out too late that they implement only those particular features which the author happened to need–but rarely are these limitations described upfront, and in fact these are often the same libraries promoted as the canonical implementation of $foo in language $bar.

              1. 11

                +1 to distinguishing between “publishing” and “promoting”. GitHub’s contribution to an “open by default” mentality is awesome, but I’d love to have a first-class indicator of whether or not the author of a tool actually thinks other people should use it. Open-source-as-a-marketing-tool can be pretty harmful if it’s not explicit.

                1. 6

                  Tangentially, it amazes me how little a big, bold “NOT MAINTAINED” tag in the readme does to discourage people from using the library (and subsequently harassing you with issues).

                  I have an older PHP library which I want nothing to do with anymore, and explicitly say “This is not maintained! Do not use in production!” (and below that, the old readme still says “Alpha status, do not use in production!”). Yet I still get emails about fixing XYZ, or asking why it imploded their mission critical production code or something. I just don’t even know how to go about answering those tbh. Its. Not. Maintained. :(

                  1. 1

                    Heh. Yeah, I get support requests (or people moaning on Stackoverflow) occasionally about 5 or 6 year old versions of a library I wrote that has seen 2 major version updates since the version they are using. Often they’ve obtained the source not from me, but from random person that wrote a tutorial and provided a downloadable archive of my code hosted on their blog and never linking to me at all. Often these people remove all “unnecessary” files like README, INSTALL and LICENSE. Grrr…

                    This library is an Objective-C one, and I released a new minor version almost exclusively devoted to conversion to ARC. This resulted in lots of moaning from people who upgraded without reading the documentation and thought my code had terrible memory leaks. I had to make it impossible to compile without ARC enabled to make those stop… So yeah, my experience is that people don’t tend to read documentation much… :-)

                  2. 4

                    I think the answer to this is essentially that not every release is for the purpose of trying to get people to use it. Also, authors are not necessarily aware that their reasons aren’t the same as everyone else’s, and that makes it harder to be proactive about making only the right promises given how people from other contexts will interpret them.

                    More than half the project pages I land on assume I know something about some highly specialized field like audio engineering or 3D modeling, and that I know that their project is in that field, when actually I’ve never heard its name before and they don’t clearly describe the project’s purpose anywhere on the front page.

                    I see this as the same problem. Quality expectations that an author doesn’t realize they’re exuding are a special case of all the expectations that an author doesn’t realize they’re exuding. Fix that first. :)

                    1. 2

                      This is a very interesting point. The question is how much “coverage” of a spec do you need and isn’t it OK as long as you document the limitations?

                      For example, I once wrote a library to load data from a particular file format. I handled some edge cases that I came across in my own work, but did not bother to cover many others. Notably, my library would only work with the version of the file format I was producing for my work, but not for earlier (and now later) versions.

                      My idea in releasing the library as open source was the hope that not only would some one be able to use it, they would be able to build upon it to add the edge cases they needed etc.

                    2. 6

                      This is an important case to make. I agree with everything it says, and I know that the attitudes it’s implicitly responding to are prevalent in open source. I’d also add that people seem to feel as though they know the motivation for someone else’s project being written - but from the outside, that’s not a thing it’s easy to tell. Off the top of my head, people write open source for generally some combination of:

                      • Learning a new toolset or area of mathmatical theory
                      • Trying to bring ideas to a wider audience
                      • Being saddened by the state of software they have to use, and wanting a better alternative to exist
                      • The fun of creative expression
                      • Relaxing from a day job
                      • Building a portfolio for a future job search
                      • Meeting programmers with similar interests
                      • Feeling a sense of community participation
                      • Wanting to do one’s part to promote economic ideals about what software should cost
                      • Wanting to do one’s part to promote technical ideals about how software should have code available
                      • Hoping that someday, someone else will pick up tinkering where you left off
                      • Wanting to provide code as educational material for future people working on the same problem

                      Unless you’re actually working directly for one of the Linux distributions that advertises itself actively as something everyone should use (Debian, Ubuntu, and Mint, but not gentoo, NixOS, or anything that’s open about its experimental do-it-yourself nature), you have made no promise to anyone else about your code. If a third party expects it to be something it’s not, that’s on them.

                      That said, there’s definitely room to go deeper and investigate what attitudes, exactly, lead people to be rude and entitled about what they feel open-source software authors should do for them. And to consider what can be done about it. This article is probably for the most part preaching to the choir, though that’s important too for morale!

                      Personally, I think a lot of people see “open” and understand “free stuff” and that drops them into an entitled mindset, which, after all, many have been trained to do by living in a capitalist society which does all sorts of loss-leader marketing.

                      Disclosure: I consider the author a friend.

                      1. 5

                        I see releasing open source code in terms of how much you want to get out of it. Some people want to display coding ability, others want to share it with hopes of somebody else finding it useful, and there are the people that want to support it and have wide adoption.

                        There are projects that sit in my GitHub without anybody else seeing them. Which is fine. If I wanted to have a project like Rails or Redis (extreme examples…I know), I would have to dedicate a lot more time to anything I post there. I would imagine working on a large project akin to a full-time job or at least very close to it.

                        If your project gets attention and some adoption, then I can see being mostly responsible for maintaining it appropriately. But people who point fingers about lack of bug fixes or support forget that it is open source. Anyone can fork it and submit changes. This is how open source thrives.

                        1. 2

                          I looked your projects.
                          If it isn’t too much work I would put a version of the HTMLClock into the readme, actually on second thought I guess GitHub scrubs anything that could be used for evil from the readme before displaying it :( In that case a link to a working HTMLClock would be good.
                          Tide is interesting. parse_get is susceptible to buffer overruns. You might not care in this particular project, but I think you could also pass ../something.txt or even /System/mysecrets.txt to get files outside of the working directory. You might want to return forbidden or something if it contains ../ and if it starts with / then you might want to skip that character and assume that they mean something from the working directory. Some of your projects don’t have descriptions so if the title didn’t grab me I didn’t visit them.

                        2. 5

                          A lot of the time I open-source things by default because I want an off-site repo but I’m too cheap to pay for private hosting.

                          1. 3

                            Bitbucket gives you free unlimited private repositories for up to 5 users FYI.

                            1. 2

                              Ooh, nice to know. I’ll keep that in mind if I start a new private project.

                            2. 2

                              I have to admit, that reason never occurred to me!

                            3. 3

                              N.b.: this is not a plug; i don’t WANT anyone to use this, just for feedback.

                              I released one ruby gem in my entire career (where released is a big word); would you guys consider this “not-shitty enough to release upon the world” or would you rather have me erase this pile from existance?


                              (I’m trying to get something like a benchmark out of this ;))

                              1. 5

                                Since nobody else has given you feedback, here’s mine, although I don’t use Ruby.

                                It’s small, but small is not the same as low-quality. From Haskell I’m used to the idea that package boundaries can be chosen around clear abstractions at a fine grain, and I see many small packages as strongly preferable to a few large ones. I think the functionality you’ve included is consistent with that.

                                From a non-Rubyist’s perspective, I see no obvious red flags in the code itself, but that just means that you paid attention to formatting. :)

                                I’d definitely put this in a public github repo, if I had written it. I might or might not submit it as a gem for … wherever gems are centrally kept? That would depend on whether I felt it was an entry in an already-crowded space. If it’s something that isn’t already there, of course I’d submit it. If it’s already there, I’d think about whether I felt it was part of that conversation rather than just reiterating a code pattern that had been “said” already.

                                1. 3

                                  Thanks for your feedback, much appreciated.

                                  I agree with you on whether to submit it to gem-heaven-central: Rubygems. I decided to do so only because … well, to have created a gem to be honest. Sue me ;-)

                                  1. 2

                                    That’s fair too. :)