4 ms·

As the author of shitty open source libraries I agree, but a bit of a disclaimer in the readme should be expected.

by dnautics 6y ago

koheripbal 6y ago
Should I remove all the "TODO:" lines first?
- jimsmart 6y ago
  I don't in any of my open projects. They're there for a reason! Many of them are written in a way that is probably useful to another coder who is taking the time to look at that piece of code — whether because of an issue, or for 'fun'.
- grayclhn 6y ago
  No — they’re useful for you (presumably) which is enough reason to keep them. But they’re useful documentation too. I’ll usually search for “todo” as part of evaluating a library because it highlights what’s missing as well as the developer’s priorities and mindset.
blihp 6y ago
Unless you have something specific to point out / warn users about, why? It is what it is, and unless users contribute something back to make it better, it's cost them nothing. If they did contribute something back, then hopefully it's a little less shitty. Unless the library in question is objectively bad and/or non-functional, no apologies or disclaimers are necessary.
- jacoblambda 6y ago
  I see nothing wrong with a disclaimer along the lines of "This is a hobby project. As the author I care about this project and want it to be as good as possible but don't expect the kind of polish you'd see in projects with corporate backings." It doesn't discredit the project in any capacity, it just tempers users expectations.
  - Dayshine 6y ago
    But this is clearly the default situation for any project not hosted under an organisation.
    - jacoblambda 6y ago
      You'd assume so but as others have recently started posting in the comments on this thread, maintainers for small projects regularly get barraged with demands and spam/other forms of aggression in retaliation for not meeting said demands. I'm not sure why but some people like to assume that just because you posted something online that you must fix any problem people have while using it and add any feature that it doesn't have. I suspect that this is the main reason those "This is a hobby. Please don't get mad at me if there's a problem" README tags started showing up.
  - guggle 6y ago
    "(just a hobby, won't be big and professional like gnu) "
- strken 6y ago
  Why not? Sticking a disclaimer saying "this has basically no test coverage" at the top of your readme has negligible cost and might stop someone from being fired. Of course, there's no obligation or even expectation that you should provide such a warning, but if you're already thinking about it, might as well just do it.
  - mdtusz 6y ago
    At risk of sounding like a gatekeeper, maybe someone getting reprimanded for using an untested, production unready library isn't a bad thing. It's not realistic to read through all the source of every dependency you use, but it should be encouraged for developers to take a more active approach in evaluating dependencies they pull in - at least to check how active development is, what sort of open issues there may be, test coverage, code quality sniff tests, what the license is etc. I'd be willing to bet most GPL violations are due to ignorance, rather than intentional.
rhizome 6y ago
There's also different "shitty"'s. Some are only aesthetic/architecture features like bad CSS or a kooky object model or API or performance problems or something, but some have security vulnerabilities.
- cnasc 6y ago
  Absent an audit for a specific version of a library, you probably shouldn’t assume any random package you use is secure.
  - rhizome 6y ago
    Well there's audit-insecure and then there's FormMail.pl insecure. I'm talking more about the latter.
lumost 6y ago
When I find an open lib on github that looks to solve the problem I have, and it has a "warning! don't use" on it - I assume this means the author has no intention of maintaining the library, accepting patches, or preserving backwards compatibility. Contrast this with the standard assumption - I'm using random code off the internet with a good faith effort by a maintainer not to break my stuff. If I find things broken, I may upstream a patch to said maintainer - or decide it's not for me and move on. I never go through the latter effort when there is a big warning on the Readme.
- dnautics 6y ago
  That's right, but you can be more specific. "Warning: code quality isn't great. PRs accepted". Or "warning, experimental" etc.
matheusmoreira 6y ago
> a bit of a disclaimer in the readme should be expected Every project already has these. They're in the license files. > This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. This disclaimer is clear, self-explanatory, legally binding and a standard feature of all licenses. So why do people assume they can use random code from random developers they never met without even looking at the source code?
- brabel 6y ago
  > So why do people assume they can use random code from random developers they never met without even looking at the source code? Because that's open source, and has worked well for a lot of things.
  - watwut 6y ago
    That us not how open source ever worked. You get high quality open source from established projects and stability from governance. By governance I mean something like apache or eclipse or linux foundation that forces projects to be lead in certain way. Random code from random people always had varios quality - from great to horrible.
- mjw1007 6y ago
  I don't think it's good to rely on the licence to carry this sort of information. Even if I have a library that I intend to maintain as polished and continually updated code, I'm going to have a licence disclaiming a legally-enforcible warranty. And I might have a library that over the years changes from being shitty to high quality (and back!). I wouldn't want to go changing the licence to follow its lifecycle. I think it would be valuable to have some widely understood conventions of text you can put in the README to set appropriate expectations.
- foldr 6y ago
  >legally binding Counterintuitively, absolute disclaimers of warranty aren't legally binding in many jurisdictions. So don't assume that you are legally absolved of any responsibility just in virtue of having this line in the license.
guggle 6y ago
Here's one of mine in the README: Warning: [ShittyFrameworkName] is just a personal toy framework: * It will break compatibility from commit to commit with no warning whatsoever. * It has (almost) no tests * It has (almost) no documentation. * It's (mostly) not php-fig friendly * Its code only cares about the needs of its author
tastroder 6y ago
Tend to disagree w.r.t. the disclaimer tbh. Be it GitHub or package manager of choice I don't get where the default assumption became "everything on here is curated and production ready" rather than "this is something a 15yo built 5 years ago while on shrooms". That's part of due diligence, if I use something that isn't explicitly marked as maintained or don't understand the state it's in that's on me imho.
addHocker 6y ago
Having PR-Material in ReadMe.md is the source of success, cause everyone who tries, is a free-contributor until it works.

As the author of shitty open source libraries I agree, but a bit of a disclaimer in the readme should be expected.

koheripbal 6y ago

Should I remove all the "TODO:" lines first?

jimsmart 6y ago
I don't in any of my open projects. They're there for a reason! Many of them are written in a way that is probably useful to another coder who is taking the time to look at that piece of code — whether because of an issue, or for 'fun'.
grayclhn 6y ago
No — they’re useful for you (presumably) which is enough reason to keep them. But they’re useful documentation too. I’ll usually search for “todo” as part of evaluating a library because it highlights what’s missing as well as the developer’s priorities and mindset.

blihp 6y ago

Unless you have something specific to point out / warn users about, why? It is what it is, and unless users contribute something back to make it better, it's cost them nothing. If they did contribute something back, then hopefully it's a little less shitty. Unless the library in question is objectively bad and/or non-functional, no apologies or disclaimers are necessary.

jacoblambda 6y ago
I see nothing wrong with a disclaimer along the lines of "This is a hobby project. As the author I care about this project and want it to be as good as possible but don't expect the kind of polish you'd see in projects with corporate backings." It doesn't discredit the project in any capacity, it just tempers users expectations.
- Dayshine 6y ago
  But this is clearly the default situation for any project not hosted under an organisation.
  - jacoblambda 6y ago
    You'd assume so but as others have recently started posting in the comments on this thread, maintainers for small projects regularly get barraged with demands and spam/other forms of aggression in retaliation for not meeting said demands. I'm not sure why but some people like to assume that just because you posted something online that you must fix any problem people have while using it and add any feature that it doesn't have. I suspect that this is the main reason those "This is a hobby. Please don't get mad at me if there's a problem" README tags started showing up.
- guggle 6y ago
  "(just a hobby, won't be big and professional like gnu) "
strken 6y ago
Why not? Sticking a disclaimer saying "this has basically no test coverage" at the top of your readme has negligible cost and might stop someone from being fired. Of course, there's no obligation or even expectation that you should provide such a warning, but if you're already thinking about it, might as well just do it.
- mdtusz 6y ago
  At risk of sounding like a gatekeeper, maybe someone getting reprimanded for using an untested, production unready library isn't a bad thing. It's not realistic to read through all the source of every dependency you use, but it should be encouraged for developers to take a more active approach in evaluating dependencies they pull in - at least to check how active development is, what sort of open issues there may be, test coverage, code quality sniff tests, what the license is etc. I'd be willing to bet most GPL violations are due to ignorance, rather than intentional.

rhizome 6y ago

There's also different "shitty"'s. Some are only aesthetic/architecture features like bad CSS or a kooky object model or API or performance problems or something, but some have security vulnerabilities.

cnasc 6y ago
Absent an audit for a specific version of a library, you probably shouldn’t assume any random package you use is secure.
- rhizome 6y ago
  Well there's audit-insecure and then there's FormMail.pl insecure. I'm talking more about the latter.

lumost 6y ago

When I find an open lib on github that looks to solve the problem I have, and it has a "warning! don't use" on it - I assume this means the author has no intention of maintaining the library, accepting patches, or preserving backwards compatibility. Contrast this with the standard assumption - I'm using random code off the internet with a good faith effort by a maintainer not to break my stuff. If I find things broken, I may upstream a patch to said maintainer - or decide it's not for me and move on. I never go through the latter effort when there is a big warning on the Readme.

dnautics 6y ago
That's right, but you can be more specific. "Warning: code quality isn't great. PRs accepted". Or "warning, experimental" etc.

matheusmoreira 6y ago

> a bit of a disclaimer in the readme should be expected Every project already has these. They're in the license files. > This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. This disclaimer is clear, self-explanatory, legally binding and a standard feature of all licenses. So why do people assume they can use random code from random developers they never met without even looking at the source code?

brabel 6y ago
> So why do people assume they can use random code from random developers they never met without even looking at the source code? Because that's open source, and has worked well for a lot of things.
- watwut 6y ago
  That us not how open source ever worked. You get high quality open source from established projects and stability from governance. By governance I mean something like apache or eclipse or linux foundation that forces projects to be lead in certain way. Random code from random people always had varios quality - from great to horrible.
mjw1007 6y ago
I don't think it's good to rely on the licence to carry this sort of information. Even if I have a library that I intend to maintain as polished and continually updated code, I'm going to have a licence disclaiming a legally-enforcible warranty. And I might have a library that over the years changes from being shitty to high quality (and back!). I wouldn't want to go changing the licence to follow its lifecycle. I think it would be valuable to have some widely understood conventions of text you can put in the README to set appropriate expectations.
foldr 6y ago
>legally binding Counterintuitively, absolute disclaimers of warranty aren't legally binding in many jurisdictions. So don't assume that you are legally absolved of any responsibility just in virtue of having this line in the license.

guggle 6y ago

Here's one of mine in the README: Warning: [ShittyFrameworkName] is just a personal toy framework: * It will break compatibility from commit to commit with no warning whatsoever. * It has (almost) no tests * It has (almost) no documentation. * It's (mostly) not php-fig friendly * Its code only cares about the needs of its author

tastroder 6y ago

Tend to disagree w.r.t. the disclaimer tbh. Be it GitHub or package manager of choice I don't get where the default assumption became "everything on here is curated and production ready" rather than "this is something a 15yo built 5 years ago while on shrooms". That's part of due diligence, if I use something that isn't explicitly marked as maintained or don't understand the state it's in that's on me imho.

addHocker 6y ago

Having PR-Material in ReadMe.md is the source of success, cause everyone who tries, is a free-contributor until it works.